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by Ben Batimer 


Ecrix VXA Tape Drive 

After liaving suffered through several years and many pounds 
of DLT Ill rapes on our old APS DLT III 2000 XY backup tape drive, 
we recently made the switch to Ecrix's new VXA tape drive, w^hich 
uses revolutionary tape technology to produce extremely reliable 
backups on pint-sized tapes. So far, we’ve been pleased with the 
performance of tlie Ecrix drive, but in order to capitalize on the 
VXAs state-of-the-art technoiogy you will need some significant 
liardwaie thitt you may not be willing to allocate to a backup server. 

There are three main advantages that the Ecrix VXA 
drive claims over your standard DLT or DAT drive: speed, 
reliability, and cost* As we all know; FireWire offers data 
transfer rates at up to 400 Mphs, wdiich can be twice as fast 
as your old SCSI interface. Although this sounds like a great 
savings, the likelihood of your backup server to achieve 
these speeds in practice is questionable. If you are backing 
up clients over a netwa^rk, your maximum data transfer rate 
is already limited by the speed of the network (most likely 
10 or too Mpbs), making the speed advantage of FireWire 
over SCSI inconsequentiaL It really doesn't matter how fast 
your computer can write to the tape if it’s slower than the 
speed at which the computer can get the data from the 
client. For local backups, however, FireWire makes all the 
difference, and backup rimes will drop significantly. All of 
this assumes, of course, that you have a FireWire capable 
machine available as a backup server. We use a PowerMac 
8500 waih a G3 card and a PCI FireWire card. Substituting the 
Ecrix drive for our old SCSI DLL drive did not result in faster 
backups over the network. On local backups, however, I w^as 
able to achieve a top speed of a whopping 360 MB/min.! 


APS DLT 2000XT (SCSI)Local {MB/min.> 

Remote (MB/mim) 

SuAtnifiiible Speed 100 

50 

Maximum Speed 120 55 


Figure L Backup SI}eeds for Ibe DLT SCSI Dme 


Ecrix VXA (FireWife) 

Local (MB/mlti.) 

Remote (MB/mlti.) 

Susiainable Speed 

250 

50 

Maximum Speed 

360 

55 


f igure 2. Backup Speeds fanbe VXA FiwWire Drive 


As the tables above show quite clearly. Retrospect can write 
up to tliree times as fast to the VXA FireWire drive as it can to 
the DLT SCSI drive. However, on network backups, there Ls no 
discernible difference in speed t>etween the twx) drives. Clearly, 
the network is the t>ottieneck in this example, and the superior 
performance of the VXA drive is lost. We have about 35 client 
machines in cjur backup cycle, and all but one (the backup 
server itself) are acces.sed over a network. For us, the gains of 


the VXA drive pale in comparison to gains we could make by 
upgrading our network speed. Since the whole idea of a backup 
server implies reliance upon a network, most people interested 
in the VXA drive will probably have a similar experienc'e. While 
the drive itself functions brilliantly, it will probably not 
significantly improve the speed of your backup cycle if you are 
primarily backing up over a network. 

As for reliability, 1 did not take tlie opportunity to dip my VXA 
tapes in a pot of coffee or base them down. Personally I have never 
liad a [>roblem with backup ta[3es deteriorating, but even the threat 
Ls disheartening. The VXA drive uses a new technology involving 
packets tliat Ectix claims w'ill gmatly decieiise tlie likeliliood of losing 
data on a Ixackup tape. Just as network tnifhc moves in packet fonn, 
tile VXA drive writes only packets to the tape. Combine this with an 
interpolation algorithm, and VXA suddenly liecome remarkably 
reliable, since large chunks of the tape must Ix.^ missing in order to 
make the tape unreadable. For a nilty demonstration of tliis 
technok;gy -see httpi//w ww^^ecrixxt>m/vxa/. 

The diminutive physical si/je of the VXA tapes (roughly tlie size 
of audio cassette tapes) is a big plus if .storage space is even a small 
concern, as backup sets tend to build up Fast. Althcxigh the tapes 
are lelalively expensive ($79.95 for the 33/66 GB V17 tapes), their 
price per gigabyte (-'$1,21) is slightly less Than that of the DLT tape.s 
that we were buying ($3H for 15/30 GB tapes, “$1.Z7/GB). However, 
with iiaKiwate compression on, I w'as only able to squeeze a 
maximum of 52 GB onto one of the \XA tapes, and an average 
closer to 45 GB. Comparatively, the DLI' tapes averaged alxiut 25 GB 
per tafie, with a high of 28.5 GB. This makes both the effective 
average price per GB ($1.78, $1.52) and the effective maximum 
storage price per GB ($1.54, $1.33) swing in favor of the DLT tapes! 
While the price of DLl* 15/30 tapes lias been rising and will likely 
continue to do so, it is notew^orthy that they come in under the VXA 
tapes in elTective price per gigabyte. Also, Ecrix does offer two other 
tape types tliat all work with the VXA drive — the VIO (20/40 GB 
for $44.95) and the V6 (12/24 GB for $29.95). 

While the Ectlx VXA HieWiif tape drive is clearly a superior 
prcxliict, it is necessarily tlie solution to your backup woes. If you 
rely heavily on network backups, the VXA drive will likely not niiike 
much of any improvement in backup time over ycjur existing tape 
drive. However, if you exjneentmte your backups on lex's! disks, then 
the .speed of the FireWire VXA drhe will slice your backup rimes in 
lialf' or even in thirds. On the basis of pric^, there is no significant 
advantage to the VXA tapes over tlie DLT tapes (although that may 
change as outside vendors begin cloning and selling these VXA 
tapes). As for reliability, I cannot confirm or deny the ambititxis 
claims of Ecrix, but after liaving used the drive for a few^ montlis, I 
have no mmm to doubt tliese claims. I Ime no doubt that this drive 
w^ill provide a fantastic solution in the right environment. Ki 
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MAC OS X 


By Dan Wood, Alameda CA 


What happened to my System Folder? 


Learning The Directory Structure of 
Mac OS X 

Introduction 

Longtime Mac users have gotten used to the layoui of a 
Macintosh system. The System Folder holds all the files 
distributed by Apple, along with anything that you or your 
applications installed. Your files and applications can go 
anywhere, though predefined ApplicaLions and Documents 
folders have given you some suggestions on where to pul your 
files. But overall, you had complete control of the layout and 
contents of your hard disk. 

With Mac O.S X, all of this has changed. The disk layout 
has little in common with the structure that u.sers and 
developers on Mac OS 9 are used to. Getting used to this may 
take a little time and patience, hut there is some rationality 
behind these changes. The goal of this article is to familiarize 
the developer or technical user with this new structure. In 
this article, HI he introducing the new structure of the Mac 
OS X volume and concepts of domains; Ml delve into the 
sacred Library folders; Fll touch on file packaging, and Fll 
expose the hidden Unix layers underneath. 

A History Lesson 

Early Mac systems only had a few files on a volume — after all, 
we were working with 800K floppies —l^ut by tlie age of hard drives, 
a volume was likely to contain hundreds d' Hies. It was diffictilt to 
keep track of the contents of a System Folder in System 6. System 7 
alleviated this problem by creating sub-folders to hold fonLs, control 
panels, startup items, and so forth. This ce^t^:liniy helped, but soon 
tliis oitegorization got out of hand. Just lake a kx)k in any Extensions 
folder in Mac OS 9 and yotfll see what 1 mean. 

A major problem with the “classic"' System Folder layout i.s 
that it was next to impossible to keep track of the files installed 
by Apple and the files in.stalled by your own applications. If you 
were repairing a hard disk and you needed to re-lnstall your 
system, the prcKess of making a clean install and then moving 


over the user-installed preferences, extensions, fonts, control 
panels, and other files could easily suck up a day. 

Older versions of Mac OS were never designed for a multi¬ 
user environment. Sure, Mac OS 9 gave us multiple users, but 
some inelegant retrofitting had to be performed on Apple’s part 
to gel this to work; many applications were not written with 
multiple users in mind and do not perff)rm cxirrectly in a multi¬ 
user environment. 

New Paradigms 

On Mac OS X, many of the problems of maintainability and 
working in a niulliple-user environment are gone. Although this 
may take some getting used to, one important paradigm shift is 
that the disk Ls not really “owned" by the users as it has been in 
the past. (Some of the reasons that the disk is laid out the way 
that it is comes from Mac OS X's BSD Unix underpinnings; other 
reasons come out of the OS’s ancestry from NeXT.) Perhaps this 
seems draconian, but the fact Ls that computers are a lot less 
forgiving of missing files than humans are. By protecting the files 
that the Mac needs to operate from the average user^ the Mac is 
much more likely to stay functional. 

So ratlier dian allowing the average user to put any file 
anywhere, the user has a liome directory normally located wdthin the 
/Users directory That liome directory is pre-populated with several 
sub-folders. Up at tlie top level, there is an unwritable folder called 
System tliat doesn’t hold the files one wcjuld liave seen in older 
versions of Mac OS, along with a Library^ directory as well. The 
Network icx)n at the highest level beckons mysteriously with .several 
empty folders. And there are do^jens of hidden directories holding 
even more hies. Rest assured, this ’will all be explained, 

A user looking inside the System folder may be surprised to 
see only one item in it, a folder called Library What happened 
to all the folders and files that lived in the System Folder? On Mac 
OS X, a new paradigm is that these kinds of files are hidden, 
rather than being visible and available for accidental destruction. 

Solving the problem of separating the user’s files from 
Apple-provided folders is another paradigm shift. On Mac OS 9, 
many users like to label all Apple-provided files with a distinctive 


Dan Wood is a long-time Macintosh developer who started learning about Mac OS X teclinologies immediately after Apple acquired NeXT. After 
developing on the Mac using MacFonh, Lightspeed Pascal, Think Class Library, Metrowerks PowerPlant, and Java, he has recently gained experience 
in the Cocoa frameworks and says that There’s no going back." Mr. Wood was also the lead courseware developer on Apple's week-long training 
course for Mac OS X Server administration. You can reach him at dwood@karelia.cora. 
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color after a clean install so that it’s easy to visually separate the 
user-installed files from the Apple-installed files within the 
System Folder. By sorting by label in the Finder, for example^ one 
could quickly determine which of their control panels were 
installed initially and which were installed by them, Mac OS X, 
on tlie other hand, separates all of the Apple-pix>vided files from 
the user-installed files. 

Domains 

One innovation descending from NeXT is the concept of 
parallel directories with different owners. Once this concept is 
understood, much of the overall structure becomes clean On 
Mac OS X, there are essentially four places, which called 
domains, where files that need to be found by the OS itself can 
live. According to Mac OS X:System Overview, a domain is “an 
area of the file system segregated from other domains and with 
structural elements identical to other domains.” (Don’t you love 
circular definitions?) Perhaps ifs clearer to examine domains by 
enumerating through tliem. 

The first domain where files live is on a per-user basis, on 
tlie local liaid drive. This Ls where a user’s personal dcxnjmeriLs and 
preferences reside in a typic'al setup of Mac OS X. 

The second domain is in a plate accessible to everybody on 
the local machine, regardle.ss of who is logged in. Useful things 
to put in such a directory are drivers for peripherals, Internet 
configuratioas, fonts, documents to be served by the machine if 
it is being used as a Web server, and so forth. 

The third domain, one that is largely unused unless you 
happen to have your Mac configured to run on a network of 
Macintoshes, is the local area network, Doaiments, applications, 
and configurations relevant to an entiie group of users and 
computers (say a classroom or office environment) can all live 
on the network rather than iieing copied to everybody’s local 
machines. This is a powerful but underutilized capability of Mac 
OS X, one that makes network administration much easier than 
ever before. (I expect that Apple will begin promoting this 
capability in the near future ) 

The fourth domain is in a directory owned entirely by 
Apple; that is, only Apple-supplied files live there. This directory 
is write-protected from the non-administrative user, because a 
user really has no business changing the contents of that 
directory Think of how much easier it is to upgrade your system 
if one doesn’t have to sort out the Apple-supplied fdes from the 
third-party files! 

These four domains for files to reside in correspond to 
specific directories on a Mac OS X system. If you haven’t already 
guessed, it boils down to these locations: 

Per-iiser: A user's home directory* located in the /Users 
folder [frequermly abbreviated as 

Per Macliitiep often called “Local**: / (the root, top-level 
directory; the contents of your hard disk) 

Local area network: /Network directory 
Apple provided: /System directory 


Oh yes, there’s sort of a fifth domain, and that is your iDisk. 
Apple has been pushing integration between Mac OS X and 
iDisk, so naturally there is some overlap here. Many of the top- 
level folders in your home directory have the same names and 
purposes as the top-level folders on your IDlsk. Most of the iDisk 
folders are merely suggested locations for a user's files, so they 
will not be discussed further. 

The Second Level 

If you start to browse around in these directories, you will 
begin to see some similarities in their contents. Let’s look at the 
some of the sub-folders to be found in the four domains* 

Ufici: Local Network System 
Applications Applications 
Desktop 

Library Library Library Library 
Sites 

Users Users 

In Mac OS 9, you will recall that the System Folder on your 
hard disk aintain all sorts of files — Apple-installed files, files 
shared by everybody on one machine, documents for each user, 
and so forth — all overlapping. On Mac OS X, these are 
separated, but then still categorized by this second level. (These 
second-level folders are somewhat akin to the System Folder 
sub-folder separation found in Mac OS 9.) 

• Applications; AppUauions can really live anywhere, but in a 
few cases where applications need to be found by the system 
(such as those providing services), they do need to re.side in the 
Ap[^lications folders (or sut>folders theIe^lf). Unfortunately (for 
cx>asistency ) or fortunately (for ease (jf use), Apple broke their 
own “ rules” descrilxid here by putting txith Apple-supplied 
apps and user-supplied app in the same folder: There is no 
/System/Applicatioris. In earlier versions of Mac OS X and Mac 
OS X Servei; Apple apps and third-party apps lived in separate 
folders. Apple apparently decided it wasnt wxjrth the user 
confusion of having to look in two places for their applications. 
Note die diiectory for network-based applfoations; this is likely 
an empty directory on your own installation. If ^t>u are on a 
Mac OS X network that is configured properly your office-wide 
applications can be acc'essed as transparently as your own local 
applications. And individuals ciin use applicratitias available 
only to themselves by installing applications in their liame 
directory (preferably by making an Applictitjoas folder for 
searehabiJity leasons described above). 

• Desktop: Each user has their own Desktop folder, so that 
each user has a different set of documents living on their 
desktop* There is no single shared Desktop Folder as there Ls 
on Mac OS 9. 

• library: The Library directories, across all domains, are as 
close to the Mac OS 9 System Folder as you will find on Mac 
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OS X> The library is the catch-all place for documents meant 
to l>e read and written by applications, not people. {It is 
described in a header file as **various user-visible 
documentation, support, and configuration files, resources,'') 
In the System domain, Library holds files that are supplied by 
Apple and not meant to be modified. At the Local domain, 
Library holds files that may be modified on the local system, 
but do not exist on a per-user basis. Library files C’an live on 
the network, for files to be shared across a network. Finally, 
each user can have their own files in their own Library 
directory; per-user preferences files live in this folder. Library 
folders will be discussed in detail below. 

• Sites: A Sites folder is used to hold documents to be shared over 
the web. Files in a user^ Sites directory will be served by Afxiclie 
if Apache Is enabled and the URJ, of h\X^ J/hostrmme/-iisenmme 
Is accessed, (Documents to l^e served by the machine’s ‘‘main" 
web .site, at hnp://hostname, actuaUy Qve in 
/Library/WebServer/Documents. All, another inconsistency.) 

■ Users: Users on the local hard disk contains home directories, 
along with a single folder for sliared items. Bui die Nerwiork 
domain can contain users, which meaas that one’s home 
directory can live on a network server This means that 
somelxxly could log inro any macliine on a properly configured 
network and access their home directory including their own 
files, preferences, and desktop. Yes, Mac OS X can be configured 
to be a puie “network aimputer." 

Search Order 

Ifs a powerful concept to have parallel domains in this 
fashion. Thanks to the concept of searching doinains, its 
possible to place the files in one of the four main domains 
(^iystem, LoctiI, Network, and User) and have Mac OS X find the 
appropriate item. There is an order of searching the domains, 
such that more lfx:al files can override more global files. The 
search order moves from the most local domain (a user’s home 
directory) then to the local machine, then to tlie network, and 
then finally the unmodifiable files supplied by Apple. 

As an example, let’s imagine that we want to install a new 
screen saver, perhaps one of the nice ones available at 
www.epicware.com. The folder /System/Library/Scieen Savers 
contains the Apple-provided screen savers (Abstract, Aqua Icons, 
Beach, Cosmos, Custom, and Forest), It’s not appropriate to 
place your screen saver there, because if you wure to reinstall 
Mac OS X, you’d have to worry alxjut losing your new file. 

If a network administrator were generous enough to make 
some screen savers available to everyloody on the network, .she 
would install it such that it appeared in /Network/Library/Screen 
Savers. If you (or your machine's administrator) wanted to make 
the screensaver available to everybody on your local machine, 
you would put it into /Library/Screen Savers. (You might have 
to create the sub-lblder called Screen Savers in /Library; that's 
OK.) If you want to install the screen saver to be available only 
to you (which might be your only option if you aren’t an 


administrator and don’t have access to the other domains)^ you’d 
put it in your home folder's Library folder in a folder called 
Screen Savers, 

Once the new screensaver is installed in one of these 
places, it will be available when you go to the Screen Saver 
panel of System Preferences. Pretty cool! 

Accessing the Domains 

OK, this is a ma^zine for developers, so it’s high time we 
look at some code, or at least an APL Apple has provided an API 
for accessing the list of directories for searching in Cocoa. If you 
look in NSPathUtilities,h, you wiH see the following method: 

FOUNDATION_EXPORT NSArray 

^NSSearchPathForDirectoriesItiDomainfitKSSearchPatMJlrectory 
directory. MSSearchPathDomainMask domaitiMask. BOOL 
expandTilde)i 

NSSearchPathR)rDirectoriesInDomain.s returns an array of 
strings which you can manipulate for searching for files (or 
actually writing to, if that is appropriate. The first parameter, 
NSSearchPathDireclory; is a constant that represents the second- 
level folder wiiliin a domain, as described above. The second 
parameter, NSSearchPathDomainMask, is a mask that determines 
whether all domains should be returned (including unmodifiable 
ones), or just user-wTitable domains. The third parameter is a 
BOOL indicating whether the representing the user's home 
directory should l>e expanded to the full path or not. 

Careful examination of the first parameter, 
NSSearchPatliDirectory reveals that there are more special 
directories than those listed above. Briefiy, it should be noted that 
tlie GrabBag and Utilities directories, directories for developer, and 
documentation directories can be accessed via the above APL. Such 
a |xtih might conte in handy for; say, an installer looking for the 
appropriate directory to place a particular type of application. 

From Carbon, you can access domains using the familiar 
FindFolderO in the Folder Manager; this has been retrofitted to 
work with domains. 

The Library Folders: The Third Level 

Recall the comment that Mac OS 9’s Extensions folder, 
witliout further subcategorization, has too many items in it to 
keep track of. On Mac OS X, the Library domain is a catch-all, 
but fortunately, it is already divided into multiple sub-lblders “ 
several dozen, actually. In the intere.st of brevity, only a few 
interesting sub-folders will be discussed here. 

Application Support is for applications to put cross¬ 
application plug-ins, miscellaneous support files, and so forth. 
For example, DropStuff puts its Stuffit Engine in to the 
Application Support folder at the Local domain; Omni Web places 
bookmarks and cookie files at the User domain. (Though Apple’s 
HI guidelines state that this is where support files should go, 
many applications ignore this and place their files and folders 
directly in the Library folder at the User domain) 

Color Pickers contains different color-picking 

implementations. At the System domain, the lour basic types 
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(list, slidei; user, and wheel) can be found, Others could be 
installed at other library directories in the oUier domains. 

CoiotSync holds ColorSync prcrfiles, not surprisingly The 
priniitive profiles are found at the System domain; more standard 
profiles are found at the Lociil domain; others could be installed for 
a network or user This sub-folder is an example of one that has its 
own API for finding profiles; you would use 
CMlterateColorSyncFolderO to iterate through all available profiles at 
all domains. (If you need to work with a panicular third-level Library 
folder, check your packages Af^I for sometliing similar.) 

CoreServices (at the System domain at 
/System/Library/CoroSer\'ioes) is a useful folder to know about, only 
because many ""system” appliaidons such as the Finder, the Dock, 
and Software Update reside here. 

Exteasions holds kernel extensions, more commonly known as 
drivers. Apple provides many at the System domain; user-installed 
drivers would live at the User, Network, or Local domains. 

Fonts contains, you guessed it, Ibnts. Basic "^system” fonts aie 
found at the System domain; more fonts reside at the Local domain; 
even more could reside for ilie network or user. 

Java is used for Java support. At the System domain, yodU find 
Apple’s Java classes. At the Lcx:al domain is a Java’s " home.” At the 
User domain, Jar files can be placed for an indh idual aser. (Note that 
Apple hasn't gc^tten the wlx)le java classpath mechanLsm fully 
integrated into the Mac OS X domaias as of this writing.) 

Preferences holds preference files at the User or Local domains, 
but (inconsistently) holds the pieference panel packages in the 
System domain. 

Printers holds printer drivers. Third-party drivers could be 
installed at the User, Local, or Network domains. 

Screen Savers and Sounds contain the obvious screen savers 
and sound files. 

Startupltems contain directories ( with a specific structure) for 
items to be executed when the system Ls started. (Note that this is 
difteient from a user logging in!) At the System domain, all of the 
system-provided processes and services are loaded, Installing items 
into the Local domain allows third-party^ services to be launched 
when the machine Ls booted up For example, a datal^ase server 
such as PostgreSQL or MySQL could be started up by placing the 
appropriate script and configuration file into a folder witliin 
/Library/Startupltems. (For more details, see liiside Mac OS X:System 
Overview on Apple’s developer "Website.) 

Appucation and File Packaging 

One advantage of Mac OS X (which is also available to Mac OS 
9 but not earlier systems) is tlie croncepl d' packaging. Applications 
on the Mac have becxime so complex rliat a typical prt^gram tends 
to hav'e dozeas of .support files iastalled alongside the main 
application file. Packaging means that multiple files C'an live in a 
single folder and appear as if they were a single file from the user’s 
perspeaive, Files that w^uld have Iwed inside the System Folder or 
alongside of an application can now live in the application. This 
simplifies the user experience, but may cxmfound developers who 
are looking for the components of an application. You can look 
inside of a package (usually a bundled application l>ut sometimes a 
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document, such as an “.rtfd” file or Interface Builder '‘.nib" file) by 
using the “control” key to bring up a contextual menu and choosing 
Show Package Contents. 

The Hidden Unix DmEcroRiES 

W liave all lieard that beneatli Mac OS X lies the “Power of 
UNIX.” Well, this nieans that the BSD Unix diiectory structure is 
theie as well. The diiectories ate hidden, but die Unix-specific 
diiectories aie theie, w^aiting to be discovered by developers and 
system administrators. 

The Unix-like directories are them because so much of Mac OS 
X (and the software that runs on OS X) requires these directories to 
exist. They are hidden because for the mast part, only .somebody 
who knows anything about Unix is actually going to need to access 
them. To navigate around these directories, you can use the Terminal 
and standard Unix commands like Is and cd. If you w ant to see these 
hidden files and diieaories from the Finder, you t'an enter the 
following command in the Terminal: 

defaults write com*apple*Finder AppleShowAllFiles YES 

After restarting the Finder (by logging out and then logging in, 
or using R>n^ Quit... from the Apple Menu), you will see all hidden 
diiectories as well as the hidden files diat begin with When you 
want to gp back to a simpler view, repeat tlie alxive instructions with 
NO instead of YES. 

Ycju will see many rcx:^t4evel directories familiar to users of 
Unix systems, such as /etc, /bin, /shin, /van /tnip, and /usr. Apple 
does not encourage developers to use tliese diiectories, but 
provides them for compatibility with other Unix-based operating 
systems. (Pt^rting and installing generic BSD Unix software ^— say 
from the BeeBSD Ports aillection at http ://wvvw, freebsd.org/ports/— is 
often trivially easy and there are countless opportunities for adding 
a Mac Ul over command-line ttxjls!) 

Explaining the Unix directories is beyond the scope of this 
article — a good book on BSD Unix will help. (Be sure to read 
up on BSD Unix variants like FreeBSD, not on Linux — they 
have evolved along separate paths.) There are some significant 
differences, such as the way that Mac OS X manages users 
through Netlnfo, but almost everything in BSD Unix has an 
analog in Mac 05 X* 


CONCUJSION 

So what happened to your System Folder? Well, it's still 
there in functionality, but it has been partially hidden and 
partially rearranged. It is a new way of thinking, but in the long 
run, both the average user and the power user are better off 
Maintenance is simplified by separating the a>mponents that 
make up the operating system into separate domains. By 
separating Apple-provided resources from user-installed 
resources and by allowing such resources to be available for an 
individual user, a particular macliine, or even an entire network 
of machines, administration of Macs can be much easier than it 
has ever been. As a developer, you need to consider these new^ 
paradigms (and new APIs) when writing your kiUer app. Kj 
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MAC OS X 
TECHNOLOGY 


By Jem Miltner 


The Databrowser Control 


Leant to leverage the power of Finder¬ 
like list and column views 

Introduction 

While the main focus of the Carbon API set was to provide 
an easy upgrade path for existing "classic” Macintosh 
applications to Mac OS X, starting with CadxjnLih li, ^ number 
of new APIs were "ported back" from Mac OS X to l>e available 
in the Mac OS S/9 version of Carl>on. 

One of the moa* prominent additions is the databrowser 
control, which allc}ws programmers to add Finder-style cmtiine or 
column views to their applicatioas in a native look ^ feel. Up to 
now, there have been numerous listManager replacements that 
support multiple levels of hierarchy. Databrowser pursuits to 
replace them wiih a native Mac OS control thafs flexible enough 
to accommodate most applications’ needs* 

Figure 1 shows the databrowser control in Lxjth list and 
column view mode, although I’m sure most readers will already 
have seen the databrowser in the Mac OS X Finder 



Figure 1: Databrowser in Mac OS X, 
in columit and list view mode. 


In this article, III focus on using the more general databrowser 
features* Databrcwser is a very rich control, so it's not possible to 
cover each and every feature in a single article, hut I hope that after 
having read this article, you will feel comfortable enough with 
databrowser to give it a try if you aren't already using it. 

General Concepts 

Databrowser differs from the “regular" controls in a 
number of ways. The most obvious difference is its 
complexity. However, the most important difference is, that in 
contrast to the “classic" controls we all know since 1984, 
databrowser doe.s not manage all the data itself, but instead 
calls back into your application whenever it needs some of 
the data being displayed* 

This concept of abstracting the U1 from the data model is 
very important and allows for a great variety of data being 
displayed as well as the timeliness of the displayed 
information. It also allows you, the programmer, to decide 
how you want to store your data. Whenever databrowser 
needs to access some data, it’ll call back into your application 
and request data. Ifs the up to you to retrieve the data from 
your storage and convert It into a form that databrowser is 
able to use. 

Databrowser identifies items (rows) by a unique 32-bit 
item ID. Each item has multiple properties, which are 
identified by a 32-bit property ID* I'here are a number of 
predefined properties Ce.g. whether the item is a container, 
whether the item is mutable, whether the item is active, etc.) 
and Apple reserves the range [0*. 10241 for these predefined 
properties. The rest of the property ID space is available for 
custom properties, usually represented as columns in the 
databrowser, ire. when databrowser needs to know about the 
data for a given column, it’ll call your item accessor callback 
with the property ID you assigned to the column when you 
added it* Thus, when we speak about cells in databrowser, 
they are identified by item ID plus property ID. Apple's 
Technote on databrowser (TN 2009) also illustrates this. 


Jens Miltner <:jum@niac.conn> works for Netopia where he’s responsible for the design of neiOctopus’ cross-platform application framework as well 
as the framework’s Macintosh implementation. When he’s not tw'isting bits & bytes, you can probably find him chasing through the house with his 
two litde sons or playing basketball. 
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Databrowser supports a number of different display types 
for the data, including (among others): text, icons, date/time, 
checkboxes, etc- (Figwre 1 shows an example of different 
column types)- It’ll also track user interactions with the ceEs 
automatically (if the cell in question is modifiable): for 
example, it allows the user to toggle checkboxes, make 
choices from popup menus and do inline editing of text. 

Another important fact is that databrowser only knows 
about visible items (visible in the sense of 'theoretically 
visible’, i.e, they don’t have to be on the screen, but they must 
be revealed in the hierarchy). As soon as you close a 
container, the items inside the container are removed and 
databrowser forgets about them. When you add items to a 
container, that container is automatically opened. Again, it’s 
your task to remember the Item hierarchy, but this also gives 
you more freedom in where you store information about the 
hierarchy (e.g. wdien browsing a file system, the hierarchy is 
already available in the file system itself). 

As containers are opened or closed (either 
programmatically or by the user), databrowser will send you 
notifications. You should respond to the “container opened” 
notification by adding all the items that are inside the container. 

To find out which iienis are containers, databrowser will 
just call your item accessor callback to request the “item is 
container" property for the item in question. If the item is a 
container, databrow^ser will display the disclosure control and 
allow you to add items into a subhierarchy of this item. 

One nice detail about databrowser is that notifications 
are sent in a very consistent manner, so you can rely on them 
to always show’ up, independent of what caused the 
underlying action. For example, you’ll receive a notification 
whenever an item is being removed. Now, an item may be 
removed implicitly because the item’s container was closed or 
removed, which causes databrow^ser to remove all items 
inside this container. Or an item may be removed because 
you caOed the API to remove that item. Or the item may have 
been implicitly removed because you disposed the 
databrowser control. 

Databrowser will send you the ’'item was removed” 
notification in any of these situations for any item that was 
removed (and of course in the correct order, i.e. first the 
children then the parent). The nice thing abtjut this is that 
you can use this notification e.g. to clean up a cache you 
maintained for the item’s prtjperties and you can rely on the 
fact that this notification will he sent eventually, so this is the 
only place you’d need to implement code for cache cleanup* 

What’s in there for you? 

By using the databrowser control to display your data, 
you ensure a consistent user interface experience for your 
customers: Every Mac user knows Finder’s hierarchical file list 
view and a substantial number of users will become used to 
Mac OS X’s Finders column view, so this is how many of 
them would expect the look-and-feel of other hierarchical 


browsers to be. Therefore, Finder certainly sets a standard for 
displaying data in list form on the Macintosh. 

Until databrowser came along, applications used to 
provide a more-or-less complete copy of the Finder’s 
hierarchical table view. While most of them looked very much 
like the Finder, there were slight differences in the behavior, 
which introduced yet another modal state. More important, 
though, is the fact that the Aqua look of databrowser on Mac 
OS X now is very different from the appearance on Classic 
Mac OS, so all those applications would need to rev their code 
and adjust to the new Aqua browser look and feel if they w^ant 
to provide a consistent UI experience. 

If you use databrowser for y[]ur list and column views, 
you isolate yourself from the details and differences in look 
and feel on each platform, and instead can concentrate on 
implementing the algorithms for gathering and modifying the 
data being displayed* Leave the details on how to properly 
display the data on each platform to the Apple engineers! No 
more playing catch up with the latest UI changes on the next 
version of the OS! 

And, of course: the next time your fellow Windows 
programmers try to tease you about how Mac programmers 
have to assemble everything from tiny bits and pieces, show 
them this beautiful beast - and don’t forget to ask them about 
a system control that can display hierarchical lists Mid 
multiple columns -) 

The Details 

In the next section, Fd like to show- how' you actually go 
about creating and configuring a databrowser so it’ll present 
your data in the way you want. 

Don’t fear the API 

In order to manage the complex tasks that are mvolved 
when displaying arbitrary data, the databrowser APIs consist 
of 150+ functions (if you take a look at Control Definitions.h, 
you’ll find that the databrow'ser APIs make up for half of the 
header fiie). 

Now, don’t be overwhelmed by the size of this API set: 
For your basic databrowser, you will need only a few (maybe 
10-20) of these functions* The rest of the API set is there to 
allows you to customize databrowser to your needs* 

You will also notice that databrowser uses a very 
consistent and explanatory API naming convention, so for 
many issues, the name of an API or constant will already tell 
you a lot about its purpose* 

Also, for the purpose of event handling, a databrowser 
control really behaves like any regular control, i*e. you use 
the standard ControlManager APIs like HandleControlKey, 
HandleControlClick, DrawOneControl, etc., to pass events to 
the control It’s just that for a databrowser control, these APIs 
take on their true iow-level meaning rather than the high- 
level semantic meaning commonly associated with their 
traditional usage. 
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So, what is necessary? 

There are a few steps diat will be the same regardless of 
how you use databiowser. Later in this article, well walk through 
some sample code that shows how to use some of databiowser 
features, so you'll be able to see this in source code. 

Creation 

First of ail, you need to create the control using the 
CreateDataSrowserControl Al^! (instead of using the generic 
NewControl with overloaded parameters): 

Cont r Q1Re f b rows e rCont r oiRef; 
err = CreateDataBrowserControl ( 

b r ows e rWindow. // a WindowRef 

ScontrolBounds. // a Rectaiigle 

kDataErowserListView, 
ibrowsarControlRef) i, 

This will create a databrowser a>nm)I in iLst view mode (of 
course, you can al.so create the databrowser in column view mode). 

The next step will lie to tell the databrowser control how to 
call you when it needs to request or update your data or just 
notify you about important events. This is done by passing a 
strua full of callback function pointers to the databrowser. Tliere 
is one struct for the baste callbacks. This one is required in order 
the get databrowser to work: 

struct DataBrowserCallbacks | 

tJlnt32 version: // Use kDataBrowserLatesCnIlbacks 

union 1 

struct I 

DataBrovserltemDataUPP 
i t eniDa t aCa 11 ba ck: 

C a t aE r ows e r 11 einCoEnpareURP 
i t emC Dtnpa re Ca 1 lb ack ; 

DataBrowsetItemNotificationUPP 
i teraNot i f i c at 1 QTiCa 11 back: 

DataBrowserAddDraglteioUPP 
addDragltemCailback: 

DatafirowserAcc eptDragUFP 
acceptDragCallback: 

Dat aB r ows e rReceiveD r a gUP F 
receiveDragCallhack: 

DataBrowserPostProcesEDragUPP 

postFrocessDragCallback: 

OataBroweetlternflelpConterstUPP 
iteniHelpContentCallback; 

D at aB r o vse rGetCon t ext ualMe niltTP P 
get Con t e xtua IMenuCa 11bac k: 

DataBrowserSelectContextLialHenuUPP 
B E1ect C 0 ntext uaIMe nuCa1lb ac k: 

1 vl: 

1 u: 

]: 

The itemDataCallback is mandatory - databrowser just won't 
work if it can't access your items’ data. 

Without the itemCompareCallback, databrowser won’t be 
able to sort the items in your databrowser, so they would remain 
in the order in winch they've been added. Since there are only 
very few situations where this is desired, most databrowser 
clients will actually implement this callback. 


Unless your databrowser is only used to display a flat 
hierarchy or you won’t allow the user to undisclose items, the 
(temNotificationCallback is also mandatory, since this is where 
you receive notifications about containers being opened, so 
you can fill them with their chOd items. Pos.sible notifications 
include (among others) information about items being added 
or removed, begin and end of inline text editing sessions, 
change of selection, change of the user state (when the user 
modifies the column layout and/or sort specification), begin 
and end of a sort operation. You are not obliged to react to 
a notification, so you can safely ignore those you’re not 
interested in. 

The rest of the callbacks supply additional functionality 
that you may or may not want to implement (drag & drop, 
help lags and contextual menu suppon). 

The SetDataBrowserCallbacks API will tell databrowser to 
use your callbacks (or, if you pass NULL, to clear previously 
set callbacks). 

Another struct contains the custom databrowser callbacks. 
These are used to implement custom content properties, i.e. 
properties that don't use one of databrowser’s built-in display 
styles. One notable custom content property is the preview 
property, which is used to display the preview area ki column 
view mode (for an example, see Finder on Mac OS X: in 
column view mode, whenever you select a file, you'll see 
information about the file, plus a possible preview in the 
preview area). A discussion of custom content properties 
would go beyond the scope of this article, so I’ll just introduce 
the structure defining the custom content callbacks: 

struct DataBrqwserCustoniCallhacks ! 

UIn132 version; //UsekDataBmwscilatesCustomCall^ 

unioii I 

struct I 

Dat^BrowserCustomDr avUP P 
drawIteiiiCalLback; 

Da taBrows e rCus t omEdit UP P 
editTextCallback: 

Dat aBrows e rCu s tomHi t Te s t LI P P 
MtTest Call back; 

Dat aB rows erCtj s t omTrac kin gUPP 
trackingCalIback: 

DataBrowse rCustoeiDragRgnUPP 
dragReglonCallbank: 

Da t aB r ows e t Cu s t otnA c c ep t D r a gUPP 
acceptDragCallback; 

Data! rowsE rClist onlRe c g 1 ve D ta gUPP 
receiveDragCallback; 

1 vl: 

! u; 

1: 

This set of callbacks will be transferred to databrowser using 
the SetDataBrowserCustomCallbacks API (again allowing you to 
clear previously set callbacks by passing NULL). 

Configuration 

Now your databrowser knows how to request data, but 
it doesn’t yet know how to display data once it's available. 
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Thereforej the next step would be to tell databrow^ser about 
the column layout (assuming you told databrowser to w^ork 
in list view mode): for each column you specify what kind of 
information should be displayed (text, icons, date/time, 
checkboxes, progress bars, relevance ranking bars, sliders). 
You also specify information about formatting the column's 
cells and assign unique IDs to the columns, which 
databrowser will use to identify the columns. 

All tliis information is packaged in a structure c'alled 
DataBrowserListViewColumnDesc. The first pan of the stnict is yet 
another strua tliat describes the custom property: 

struct DatsBrowserPropertyDesc \ 

DaraBtowserPropertylD propettylD: 

DataBrowserPropertyType propertyType; 
DataBrowserPropertyFlafts propertyFlags: 

1: 

Here you specify which property ID is used to identify the 
column, you specify the cc^luinn type and also some property 
flags, which govern how this column behaves with respect to 
sorting, moving, editing, etc> 

The property ID can be any number >= 1024, The range 
tT.1024] is reser\ed for special properties that databrowser 
needs to query, which don’t necessarily correspond to visual 
data (e.g, whether an item is a container, whether an item is 
editable, whether an item is active). Property ID 0 is defined to 
be interpreted as ‘"no property”. 

The propertyType member specifies how the data is being 
displayed for this column. Tht available column types are: 

• kDataBrowserTextType for text-only columns, 

• kDataBrowserIconType for icon-only columns, 

• kDataBrowsericonAndTextType for columns containing an 
icon followed by some text, 

• kDataBrowserDateTimeType for columns showing a date 
and/or time, 

• kDataBrowserStiderType for columas displaying a slider contrt}!, 

• kDataBrowserCheckboxType for columns displaying a 
checkbox control, 

• kDataBrawserProgressBarType for columns displaying a 
progress bar, 

• kOataBrowser Relevance Ran kType for columns displaying a 
relevance ranking bar and 

• kDalaBrowserPopupMenuType for columns displaying a 
popup menu. 

Note that the column type only specifies how the item data 
is presented, not w'hat the column header itself looks like. 


The most important Rags you can specify are: 
kDataBrowserPropertylsMutable to specify that the item data 
displayed in this column may be modified. If you don’t 
specify this flag, databrowser will treat all data displayed in 
this column as read-only, and your iteniDaia callback will 
never be called to change the data for this property. So, for 
example, if you want to let the user toggle the checkboxes 
in a checkbox column, you’ll have to specify this property 
flag. (Note that modifying your cell’s data won’t be enabled 
unless both the column is declared mutable and your 
item Data callback returns true for the 
kOataBrowserltemlsEditabieProperty) 

kDataBrowserUstViewMovableColuinn to specify that the 
column may be moved to a different position by the user. 
kDataBrowserListViewSortableColumn to specify that the 
databrowser may be sorted by this column. If this fiag is 
specified, clicks into the column header will make this 
column the sort property and cause a re-sort of the 
databrowser (clicking an already sorted column again will 
revert the sort order). 

kDataBrowserListViewSelectionColumn to specify that cells in 
this column should reflect/di,splay the selection state (i,e. will 
be highlighted when selected) in minimal highlight mode 
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(which is the default for list view mode). This flag also 
specifies which columns are included in the drag image (for 
minimal highlight mode). 

There's another batch of property flags that specifies 
variants of specific column types, e.g. to have checkboxes 
toggle between 3 states, to specify how your date/time 
columns should display the date/time and to specify how the 
cell content is to be Truncated in case it does not fit into die 
column width. 

The second pan of the DataBrowserListViewColumnDasc 
struct used to specify a column is a struct called 
DataBrowserListViewHeaderDesc, which specifies list view 
specific propenies of the column: 


struct DataBrowserListVlewfieaderDesc { 
UIjit32 version; 


UIutl6 

Ulntie 


mlninrumWidtli; 
DLastimumWl dth; 


Slntlfi 

CFStringRef 

DataBrowserSortOrder 

ControlFontStyleRec 

C out toIButt 0 nCout entInfo 


titleOffset: 
tltlEStriug: 
inltialOrder; 

btuFontStyle; 
btTiCouteiitlnfo; 


For the version field, you should always specify die 
constant kDataBrowserListViewLatestHeaderDesc. 
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The minimumWidth and maximumWidth fields specify the 
minimum resp. maximum width of the column that can be 
achieved when the user resizes the column. Of course, 
specifying the same value for both fields prevents the user 
from resizing this column, making this a fixed width column. 

The titleOffset field specifies how many pixels the 
column title (and also the cell contents) will be inset, 
allowing you to fine-tune the column layout. 

The titleStrrng field, of course, specifies the text to be 
displayed in the column header. After having added the 
column, you are responsible for releasing the string if you 
allocated it. You may pass NULL if you don't want the 
column to get a title. 

The initialOrder field specifies what sort ordering to use 
when the user selects this column as the sort property for the 
first time. Databrowser will remember the last son order, so 
subsequent selections of this column as the sort property will 
return to the last sort ordering. 

In the btnPontStyle field, you can specif^^ font, size, style and 
justification to use to display the coiumn header (if you w^ant to 
change the display of the databrowser content, use 
SetConlrolFontStyle). This struct is the regular ControlFontStyleRac 
struct used to tell controls about font and color settings, but 
currently databrowser ignores any color settings. You should 
make sure, though, to set up tlie flags field correctly, in case 
databix>wser iS going to supptat colors in the future. 

Finally, the btn Content Info field lets you specify what 
kind of content is drawn for the header button. Currently, the 
only variation supported is to draw an icon by passing an 
Icon Ref This is in addition to the text specified by the 
titlestring field, so you also have the option of text only and 
icon + text column headers. 

Once you set alJ this up, you pass the structure to the 
databrowser control using the AddDataBrowserlistViewColumn API, 

Contents 

So, that's it... but wait, there’s no data yet!? Of course, 
you’ll need to tell databrowser which data to display. We'll 
get into more detail as we walk through the sample code 
later on, but basically, this involves calling the 
AddDataBrowserltems API. 

So, once again, don’t shy away from the sheer amount 
of APIs. After our step-by-step tour through the sample code, 
you should be Ihirly comfortable with the basic tasks of 
setting up a databrowser to display your data - believe me, 
there’s no voodoo or black magic involved, ifs just a matter 
of getting accustomed to the way databrowser works. 

Exaaiple: a Simple To-Do-Lkt 

let’s have a look at some code that shows how to use 
the databrowser control. In this case, a databrowser control 
is used to display and manage a simple to-do list (Figure 1 
is actually a screenshot of the sample application). 
Unfortunately, the scope of this article doesn't allow me to 
cover all the nifty features available with databrow^ser, so the 
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example focuses on the basic tasks (creating, configuring and 
filling a databrowser). However, the sample code also 
implements some slightly more advanced behaviors 
(drag&drop, help tags, preview area in column view mode), 
but I wQn\ be able to go into detail about them, so you may 
just want to have a look at the source code, too. 

All the databrowser related functionality is contained in 
the file ToDoListWindow.cpp. The class used to store 
information about a single task in the to-do list is 
implemented in ToDoltem.cpp, but this class only serves as the 
data container and does not interact with databrowser itself. 

The sample application is completely CarbonEvent driven. 
For more information about CarbonEvents, you may want to 
have a look at Apple’s documentation. Note, though, that you 
are not required to use CarbonEvents to drive databrowser. If 
you are using the “classic” WaitNextEvent approach, you just 
have to make sure to dispatch the appropriate events to 
databrowser - just like with any other control. 

Before getting started, you’ll have to make sure you set up 
your development environment correctly so that all the required 
APIs are available. If you are developing on Mac OS X, you're 
already set up correctly, but if you are developing on Mac OS 9, 
you’D need the Carbon SDK, which can be downloaded from 
Apple’s website (http://developer,apple.com/sdk). 

Ail of the definitions and declarations about the 
databrowser control can be found in the Universal Interfaces 
header file ControlDefinitions.h. As of tills writing, there are two 
different declaraticms for strme of die structs and types. The 
macro NO_DATA_ BROWS ER_TWEAKS is used to toggle l>etween 
the two definitions. Always make sure diis macro to be defined 
to be 0, since this will give you the API set thal will continue to 
exist whereas the other API version is deprecated. 

Throughout the sample code, error handling will be done 
by using C++ exceptions, most of the lime by the use of the 
ThrowlfOSErr or ThrowOSErr fimaions, the fonner raising the 
exception only if the error passed is not noErr, the latter raising 
an exception using whatever error code is passed, 

Of course, since C++ exceptions cannot be thrown 
across callback boundaries, it's mandatory to set up the 
appropriate catch handlers in the callback entry points to 
ensure that no uncaught exception will make its way out of 
the callback entry point (in which case your app would 
either silently terminate or just crash, depending on the C++ 
exception handling implementation). 

How a databrowser is born 

Obviously, the first thing youll have to do is create your 
databrowser control. Since databrowser loves to live within 
an embedding hierarchy, on Mac OS 9, you’ll have to create 
a root control manually (on Mac OS X, this Ls done for you 
by the OS), In the sample code, a control property is used 
to store the object of class ToDoListWindow with the 
databrowser control, so it can be retrieved in the 
databrowser callbacks: 


Listing 1: Databrowser control creation 

// create the root control (could be conditional for Mac OS 9 only, 

// but shouldn't harm if done on X) 

// 

Throw!f0 SE r r C C r oat eRootC ont rolC 
inWlndowRef. 
irootControl )): 

// create a databrowser control in list view mode 
// that spans the entire window 
// 

ThrowlfOSErr[CreateDataBrowserControl( 
mWindowRef, 

GetWindowPo rtBounds(mWindowKef, 
^browserBounds), 
kDataBrowserListViev, 

StraBrowser)); 

// attach a pointer to this object as a propert>' of the browser control, 

// so we can retrieve die object in the diabrowser callbacks 
// 

I 

ToDoListWindow* me(this): 

ThrowlfOSErr(SetControlProperty(mBtowser, 

kToDoListWindowP ropertyCreatG r, 
kToDoListWindowPrope rtyXag, 
fiizeof(me). 
ime]3{ 
j 

// set up our callback structure 
// 

DataBrowserCallbacks callbacks: 

InitlalizeDataBrowaerCallbacks( 
icallbacka. 

kDataBrowserLatestCallbacks)t 
callbacks,u.vl.itemDataCallback “ 
sltemDatallPP: 

callbacks.ItemCompareCallback - 
sltemCompareUPF; 

callbacks ,n,vl ^iteaiNotlficationGallback = 
sit emNotlf1cationUPP; 
callbacks ,u,vl * addDragltenLCallback = 
sAddDragltemUPF; 

callbacks , 11 ,vf ,accep1iDragCallback “ 
sAcceptDragUPP: 

callbacks,u,vl,roceiveDragCallback = 
sReceiveDragOPP i 

callbacks.u.vl.poetProcessDragCallback = 
a PostProc es sDragUPP: 

callbacks,u,vl,itemfielpContentCallback = 
slteinHelpContetitUPP: 

// 

// :md JnsLuIi die caUhacks in the databrowser control 
// 

ThrowlfOSErr(SetDataB rowserCalIbacks [ 
mBrowset, 

Rcallbacks)): 

There are two more callbacks for handling contextual 
menus for the databrowser contents that are not used in this 
sample code. The call to InitializeDataBrowserCallbacks will take 
care of initializing them, so databrowser knows they are not 
used. For the rest of the callbacks the appropriate UPPs 
(Universal Proc Pointers) have already been allocated in static 
object members, e.g, 

// initialise static member sltctnDaiallPP to be a KPP to our static 
// member function ItcniDatafboc 
// 

Da t aB row s e r It emDat aUPF 

ToDoListWindow::sltemDataDPP ( 

NowDa t aB c ows e r 11 smDat atJP P ( 

ToDoListWindow::ItcraDataProc)3 : 
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Now that the databrowser control is allocated, there is 
one more thing to prepare so that the databrowser looks nice 
when covering the entire window: Since it’s the only control 
in the window, w^e tell databrowser not to display a frame and 
focus rectangle. This is done using the SetControlData API 
(actually, it’s one of the few things about databrowser that 
doesn’t have a specific API): 

BooIeaJi frameAjidFocttS(false); 

ThrowIfOSErr( 

SetCoatrolData( 
mBrowsar^ 
kControlNoPart* 

kControlDataBrowserlncludesFraEneAndFocusTag^ 
ai^eof (frameAndFoctis) * 

^frameAndFocus )); 


Specifying the Columns 

Since we configured our databrowser to display a list view 
(aka Finder-styie hierarchical view), we also need to tell 
databrowser what columns to display. This is done by calling 
AddDataBrowserListViewColumn, passing the struct describing 
the column’s properties and behaviors described earlier. Listing 
2 is a snippet from the ToDoLlstWindow class of the sample 
code. The DataBrowserListViewColumnDesc struct is configured 
for each column and passed to AddDataBrowserListViewColumn, 
passing kDataBrowserListViewAppendColumn as the column 
position so it’ll be appended to the end of the column headers. 

Note the usage of various fomiatting flags in the column 
description for the modification date column (the last column): 
we specify how the date should be displayed and to truncate the 
date/time display string in the middle if necessary. 

Since we want to support a deep hierarchy of to-do 
items, we have to tell databrowser which column should 
contain the disclosure control (using the 
SetDataBrowserListViewDisclosureColumn API). In this case (as 
in most applications) we chose it to be the first column, 
which we also make unmovable. However, you may specify 
any column to contain the disclosure control. 

For the title column, we don’t want to rely on 
databrowser’s default algorithm of determining the column 
width based on minimum and maximum width, so after 
adding this column we explicitly specify the column width 
using SetDataBrowserTableViewNamedColumnWidth. 

For some reason, the default row height in Mac OS X 10.0 
is a little too narrow, so we’ll tell databrowser to use a row 
height of 18 pixels, which looks a iot better. 

Finally, if we have a previously saved user state, well 
restore it, so the column layout is exactly how the user left it last 
time (the user state includes the order of the column, the column 
widths and the current sorting). 

listing 2: Tol>oList Vindow;:Coa flgurcListView O_ 

ToDoList Window :;ConfigureIistView Q 

Oie databrowser list view by adding all our columns 


void ToDoListWindow::ConfigureListView (void) 

I 

DataBrowserListViewColuntnDesc coiumnDesc; 

// fill in version of column description we know 
// 

coluinnDesc.headerBtuDesc.version “ 

kDat aB r□ wae rListVIewLatestHe ad e rBes c: 

// no icons in our licidcr buttons 
// 

colujuuDesc.headerBtuDesc.btnContentlnf 0 . 
contentType ^ kContcolContentTextOnly: 

// trufommately there's a bug on Mac OS 9 that requires us to 
// ocpUcitcl)^ spccifiy the header button font. 

// so we'U sped/y to use the list view font. 

// 

colujunDesc * headerBtnDesc * btnFontStyle * flags 

“ kCoutroIllseFontMask | kContralUseJustHaak: 
columiiDesc. headerBtuDeEC . btnFontStyle. fout = 
kControlFontViewSystemFGnt; 

// wc don't want any extra margins in our columns 
// 

coluJimBesc. header! tiiDesc. tit leOff set = 0; 

// specif}^ tbe default sort order when column is first sorted 
// 

caluninDeEc. headerBtnDesc . initlalOrder = 
kDataBrowaerOrderInc reusing; 

// 

// the index column 
// 

// SCI up the column property description 
// 
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colunmDesc.propertyDesc,propertyID “ 
kindexColumn; 

columnDesc.prope rtyDesc * p ropertyType = 
kDataErowserTextType; 

COlumtiDesc . propertyDesc, propertyFlags = 
kDataBrowserLlstViewSelect ionColujEn | 
kEataBrowserListVi ewD efaultCol umnF 1 a gs: 

// and some inforntation about the column width and justificadon 

// 

colUJunDest. headerBtnDesc .mlalmuiiiWidtb “ 0; 
columnDesc-headerfltnDesc-maxlmumWidth = 80: 
columnDesc.headerBtnDesc.btnFontStyle.just = 
teFlushDefault: 

// set up the button title (empty) 

// 

coluiiiiiEese,headerBtnDeBC.titleStr±iig = NULL; 

// append the column to the end of the daiabrowser 
// 

TbrovIfOSErrC 

;: AddDataBro;jserListVlewColuEn( 
mBrovser, ScolumnOesc, 
kOataBrowserLlutViewAppendColuinn)); 

// 

// this column will be the column to contain the disclosure conmd 

// 

ThrowIfOSErrC 

: :SetDataBrowserListViewDisclosureColuranC 
mBrowser. klndexColumn, false)): 

if 

fi the checkbox column 
// 

columnUesc.propertyDesc.propertylD = 
kCompletedColumn: 

COiumuDesc.propertyDesc.propertyType " 
kDataBrovserCheckboxType; 
columnDesc.propartyDesc,propertyFlags ^ 
kDataBrowserPropertylsHutable f 
kDataBrowserListVievSortableColurm: 

// column shcjuld not be resizable 
fi 

colunLnrseac.headerBtnDesc .minlmumWldth = 30: 
columnDesc.headerBtnDeEc.maximuiaWidth = 30; 

// checktwxes look best w^hen centered in the column 

if 

columnDesc.beaderBtnDesc.btnFontStyle.Just “ 
teCenter; 

// no title 

cnlumnOeec ^headerBtnDesc, titles t ring ” NULL; 
TbrovIfOSErr( 

;: AddDataBrovserListViewColumnt 
mBrowser. icolumnOesc. 
kOataBrowserListViewAppendColumn)): 

// 

// the title column 
// 

columnOesc * propertyDesc.propertylD = 
kTitieColumn; 

coiumnDesc,propertyDesc.propertyType ” 
kDataBrowserTextType: 
columnDesc.propertyDesc.propertyFlags = 
kUataBrowserPropertylsMutable \ 
kUataBrowserLlstVlevSelectlonColumn | 
kOataBrowserLiatViewOefaultColumnFlags; 

columnDesc. headerBtnDesc .miniiiiuiiiWldth “ 100; 
columnDesc.beaderBttiDeEc.maxlmmBWidtb = 700: 
columnDesc,headerBtnDesc.btnFontStyle.Just ^ 
teFlushDefault; 


coluMELDesci.beaderBtuDesc,titleString “ 

:: CFStrlngCreateWltb^ascalSt ring C 
CFAllocatorGetDefault 0 » 

“\pTask'', kCFStringEncodlngMacRoman) ; 

ThrowIfOSEtr( 

: ;AddDataErowserList¥ievColuMi[ 
mBrowser, tcoltminDesc. 
kDataBrowserListViewAppendColumn}); 
TbrowIfOSErr( 

: : SetPataErowae rTableVlevNamedCQliiinnWidth ( 
tuBrowser. klitleColunm. 200)); 

// since we allocated the string (not using CF5TR), we have to ttJease it 
CFRelease(columnDesc.headerBtnDesc,titleStringl : 

// 

// the percentage complete column 

// 

columnDesc. propertyDesc, propertylD = 
kPercsntageColumn; 

columnDesc.propertyDesc.propertyType “ 
kDataErowserProgresaBarType; 
columnDesc.propertyDesc.propertyFlags = 
kDataBrowserLlstViewSortableColumn; 

columnDesc.headerBtnDesc.minimumWldtb = 30; 
columnDesc.headerBtnDesc.maximumWidth = 100: 

ColumoDeGc.headerBtnDesc.btnFontStyle,J ust '= 
teFlushDefault; 

if no title 

columnDesc.headerBtnDesc.titlestring ^ NULL: 
ThrowIfOSErrC 

::AddDataBrowserLlstViewColumn( 
mBtowser, ^columnDesc. 
kDataBrowserListViewAppendColumn)); 

// 

// the modification date column 

// 

columnDesc. propertyDesc. propertylD 
kLastModifiedColumn: 
columnDesc,propertyDesc.prope ctyType - 
kDataBrqwserDateTlmeType: 
columnDesc.propertyDesc.propertyFlags = 
kData&rowserLifitViewSsiectionColumn | 
kDataBrowaerLiatVlewDefaultColumnFlags | 
kDataBrowBerDateTimeRelaiivc 
kDataflrowserDateTimeSecondsToo 
kDatafirowserTruncateTextHiddle: 

columnDesc.headerBtnDesc.mlnimumWldth = 80; 
columnDesc,headerBtnDesc,rosximumWidth ” 280; 
columnDesc.headerBtnDesc.htnFantStyle.Just ^ 
teFlushDefault; 

columnDesc.headerBtnDesc.titleString 
^;;CFSt ringCreateWithPascalS t ring( 
CFAllocatorGetDefault(). 

“\pLast Modified". 
kCFStringEncodlngMacRoman): 

ThrowIfOSErrC 

;:AddDataBrowserListViewColumn( 
mBrowser. ScolumnDeac. 
kDataBrowserListViewAppendGolumn)): 
CFRelease(columnDesc.headerBtnDesc.titleString); 

// in MacOS X lOiJ.thc default row height i$ a liitie too small 
// so we’U bump this up a bit to get some decent venical spacing, 

// 

ThrowIfOSErrC 

S e tD a t aBrowa e rTableViewRowHeight( 
mBrowset, 18 )); 

if if tiiere Is a saved user state to restore, do so 

if 
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if ( ebLI StViewUserState ) 

[ 

SetDataBrowserUs6rState(iDBrowser * 
mListViewDserState): 
GFRelease(iiiListViewUserState) ; 
mListVlewUserState = NULL; 

) 

1 


How about some contents? 

The last step will be to fill the databrowser with our data. 
There are two ways to fill a databrowser with items; You can 
either add the root level items manually, or you can define an 
invisible root item and just tell databrowser to use this root 
item as the databrowser target item. 

You can think of the databrowser target item as the root 
container being browsed - think about how Finder displays a 
folder: the contents of the folder is displayed, but the actual 
root of the Finder window is the folder being displayed. In 
that case this folder would be the databrowser target. 
Specifying the databrowser target also allows you to keep 
track of where your hierarchy belongs. If you don’t explicitly 
specify a target, databrowser uses a target ID of 0 
(KDataBrowserNoltem) by default. 

Now, while the first approach (adding all root items 
manually) seems like the logical thing to do at first, using the 
second method actually is much more elegant if you have a 
hierarchy to display: When you specify the databrowser 

Webmasters! Start your web hosting 
business with edition.net reseller hosting! 

* dedicated platforms 

* single and multi-domain hosting 

■ your choice of Mac OS or Linux platforms 

* FileMaker Pro hosting featuring Lasso 

* QuickTime streaming server 

* Our web-hased control panels make it easy to 

* deploy your multi-domain server 


edition.net - 
the Fine Arts 
Network 


http://www.cdition.net • mfo@edition.net 
+1 (877) 225-3821 toll free ■ +1 (310) 379-8563 international 



target, databrowser will send you a ^container opened’ 
notification for the databrowser target item (i.e. the root 
container). Since you have to implement code to fill in a 
container’s child items in your notification callback anyway, 
you can as well leverage this code to fill the root level by 
relying on the fact that databrowser will send you the 
'container opened’ notification for the target item. 

The sample code also takes this approach, so the final bit 
will be to call 

ThrowIfOSErr CSetDataBrowserTarget [mBrowser. kRootltsm)); 

That's it! If we already have items created at the root 
level, they will now appear in the databrowser as we respond 
to the ‘container opened’ notification. From this point on, 
we’ll let databrowser do its work just feeding it with events 
like any other control Now we can focus on responding to 
the callbacks and working with our data. 


The callback functions 

Let's have a closer look at what’s done in the 
databrowser callbacks. First, let’s look at the itemData 
callback. Listing 3 shows the implementation for the itemData 
callback. This callback is used to request data, but also to 
communicate back data the user has modified by e.g. 
clicking a checkbox or editing the text of an item. In the 
sample code, the main entry point will split up between these 
two cases and dispatch to the OnGetItemData or the 
OnSetItemData member function, depending on whether this 
is a request for data or a notification about modified data: 

listing 3: Item data accessor callbac k___ 

ToDoListWiudow:: ItemDamProcO 

Main cnir>^ point the ciUhack. wil dispatch to the correct member 
function depending on whether this is a load or store opemiion 

pascal OSStatus ToDoListWindow: :IteniI)ataProc( 

ControlRef brnvser, 

DataBrowserltemlD Item, 

DataBrowBorPropertylD property^ 

DataBrowserlteinLataRef itemData, 

Boolean Eetlfalue) 
i 

OSStatus err; 

UItit32 ignoreAntualSize; 

ToDoListWlndow* toDoListWlndow: 

// retrieve iheToDt>listV&indow object we aiuehed to the browser 
err = GetControlProperty( 
browser, 

kToDoListWind owP r□pe r tyC r ea t o r. 
kToDoListWindowPropertyTag. 
sizeof(toDoListWlndow), 

&ignoreActualSize, 

^toDoListWindow); 

if ( err — noErr ) try I 
// 

// let our window supply/store the data 
// 

bool handled: 
if { satValue ) 

handled = toDoListWindow->OnSetItemData( 

item, property, itemData): 

else 

handled = toDoLlatWlndow->OnGetItemData( 

item, property. itemData): 
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// 

// if it didn't handle the pnopciiy, report an emir 

// 

if { [handled ) 

err “ errCataBrowserPropertyNotStipportedr 


ThrovIfOSErrC 

SetDataErowserltemDataText( 

outItemData. IndexCFSt ring)); 

1 

return true- 


I catch( const COSErrException^ e } I 
err “ e*Cause{); 

I 

return err: 


case kCompletedColumn: 

[ 

UIntl 6 completionState: 

ThemeButtonValue checkboxValue: 


_ completlDnState “ 

TQDoUstWUtdowtOiltietlteniDataO this - >Re solvelt emlD (InWhlchlt em) 


The getter function for datahrowser hem properties, 

Tllll return whether the requested property is supported. 

bool ToBoListWlndow:: OTi&etIteniData ( 
DataBrovserltemlD inWhichltein* 
DataBrowserPropertylD inWhichProperty, 
DataBrowserltemDataRef outItemData] const 

I 

switch ( inWhichProperty ) 

[ 

case kDataBrowserltejalsEditableProperty: 
ThrowIfOSErr{ 

SetDataBrowserIteinDataBooleanValue( 
outIteiaData ^ true)); 
return true; 


->GatCompletlon(}); 

// check completed columns and mark partially completed 
// columni) using the mixed state 
if ( completlonState “ 0 ) 

checkboxValue = kThemeButtonOff; 
else if C completionState 100 ) 
checkboxYalue ^ kThemeButtonOnt 
else 

checkboxValue = kThemeButtonMixed: 
ThrovIfOSErr( 

S e tD at a B r ows e r 11 emOa t ah ut tonValue( 
outlteraData, checkboxValue)): 
return true: 


case kDataBrowserltemlsContainerProperty: 
ThrowIfOSErrt 

SetDataBrowserltemDataBooleanValueC 
outltesiData. 

this->IsContainerItem(inWhichItera))): 
return true; 

case kDataBrowserltemSelfIdentityProperty: 

// let our plain items have a clipboard icon^ 

// the container items get a folder icon ^ of course 
// 

IconRef icon; 
if ( GetlconRef{ 

kOnSystemDlsk, 
kSystemIconsCreator. 

this->IsContainerIteEii(inWhichItem) ? 
kGenericFolderlcon ; 
kCliphoardIcan. 

Sficon) = noErr ) 

[ 

ThrowIfOSErrC 

SetDataBrowserltemDatalcon( 
outrteuiData. icon)); 
ReleaselconRe£(lcon); 

1 


// fall thru to kTitlcColumn 
case kTltleColumn: 

// retriev^c die tide from the ToDoItera object 
ThrowIfOSErrf 

SetDataBrowsarltetnDataTExt ( 
outltemData, 

this->Re s o1ve11 emlD{inWhich11 em) 
-)title)); 

return true; 

case klndexColuam: 

( 

chat IndexStr[ 256 ] : 

CFStringRefindExCFString(NULL); 

// create a string representation of the index 
sprintf{indExStr, “%u.". 

Getltemlndex( 

this->ResolveItenirD(lnWhichIteii!))): 
IndexCFString = 

CFStringCreateWlthCStrlng(NtILL, IndexStr^ 
CFStringGetSystemEncodlngO); 

// stuff the string into die ItemDataRef 


case kPercentageColmnn: 

// percentage is [O.-lOO] 

ThrowIfOSErrt 

SetDataErowserltemDataMaxiniun ( 
outltemData, 100)]: 
ThrowIfOSErrf 

SEtDataBrowserItemDataHinimum( 
outltenBata. 0)}; 

a completion is already returneeJ as percentage, 
// so we can just use that value 
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ThrowIfOSErr( 

SetDataBrowserltemDataValne( 
outltGinData. 

thls->ResolveItemID(intfhlchltem) 
->GetCciiiipletion())) ; 

return ttue: 


1 


case kLastModifiedGolumTi: 

ThroitflfOSErrC 

SetDataBrovserltemDataDateTime( 
outlteraData, 

this ->ResolveItemII> (inWliichltena) 
- >iiiodificationDate}): 

break: 


return false: 


ToDoLisi Window: :OnSetIteniDataO 


// make sure the user actually made some modilications 

If { CFStringCompare( 

uewTltlen item->title, 0) 

!= kCFCoinpareEquslTo ) 

[ 

item’)SGtTitle(newTltle); 
GetD 3 teTime(&itein->modificationDate); 

// make sure the'last modified'column also gets an update, 
// since we adjusted the item's last modification date 
// 

if ( ltenL->parent ) 

ThrowIfOSErr( 

UpdateBataSrowserltenifi ( 
niBrowsar, 
itan->parent->idt 
1, //tiumltems 

j&iteiE- >id, 

kDataBrowserlteml^oProperty, 
kLastModifiedColumn)): 


Store modifications made by the user back to our ToDoitem objects 

bool ToDoListWindow::QnSetrtemData( 
DataBrowserltemID inWhichitera. 
DataBrowserPropertylD inWhlchProperty, 
DataBroweerltGUiDataRef InOutlteinriata) 

1 

switch [ inWhichProperty ) 

f 

case kTitlaColuran: 

[ 

CFStringRef newTltle; 

ToDoitem* itom(this-) 

KesalvelteiiilD(iTiWhlchrteiii)): 

// retrieve the modified string 
ThrowIfOSErr! 

GetDataBrowserlteraDataText( 

inOutlteraData, fiinewTitls}): 


Printing reports 
on Mac OS/X P 

and Classic 

and Windows 

andXMLiflMLinTl 


OOHlEisyonr 
C++ sointion 


dm- 

-■-ror- 


'ow^r^ 


ir- 


MFC ir:;-' 


and 

Crr in!- 

mai 


www.oofiie.coni.an 

- jrt. , i dC, 


tPF 




/rtf. 

easy- 
-lory 
e and 
erver 


; liitatjon ejensra^itr /^ppMaker d Base 
^nnuie' Farfccrti c-tret.- Pi 0+4- mierfaca with 
T cross-plBi^^ :tri graphintj 


// if our sort property is either the litie or the 
// modification thte column, we’ll have to trigger a re-sort 
// of the databrowseri since UpdaieDataBrowscrTtems 
// does not trigger this autonuiijcaUy 
// 

DataBrowserPropertylD sortProperty; 
ThrowIfOSErr! 

GetDataBrowserSortPropertyC 

raBrowser, &sortProperty}}: 
if ( sortProperty ™ kLastHodifiedColumn 
I I EortPrtjperty ™ kTitleColuran ) 
ThrowIfOSErr! 

SortDataBrowserContainer( 

mBrowser. kRootltem, true)): 

I 

CFReleaaeCnewTitle): 
return true: 

i 

ease kCompletedColLitiin: 

f 

ThemeluttonValue checkboxValue: 
ThrowIfOSErr! 

GetDataBrowse rlt craDataButtonValue( 

inOutltemData. &cheekboxValue)): 

ToDoitem* item(this-) 

RGsolvelteraID{inWhichltem)): 

if ( item-)cbildlTems.empty[) ) 

I 

// for leaf items, the possible completion states are 
// either done or tioti ie.O nr 100 % 
if 

lteiii->SGtCcntipletion( 

checkboxValue == kThemeButtonOn ? 

100 : 0 ); 

// Update our parent container chain’s completed and 
// percentage column properties^ so they’ll reflect 
// the modified state 
// 

ThrowIfOSErrC 

tl pd at oDa taB rowan rl terns (ciBrowser. 
item->parent-)id, 

1, // numiteps 
Altera Old» 

kDataBrowssrltemNoProperty, 
kPercentageColuion)); 

for ( ToDoitem* container = item-)pareiiT: 
container != NULL ficfii 
container->id != kRootltem: 
container container-)parent ) 

I 

ThrowIfOSErr! 

UpdateDataBrowaerltenLs (mBrowaer, 
containGr-)parent-)ld, 

1, U numitems 
&containar->id, 
kDataBrowsorltemNoProperty t 
kCompletedColumn)): 
ThrowIfOSErr! 
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UpdateDataBrowserltems(mBrowser, 
containsr->parent->id. 

1, if numlteras 
&contalnet’'>id. 
itDataBrowserltemNoProperty. 
kPercentageColuuiii)): 

] 

// if (jur sort property is either the checkbc)3E or 
// the progress bar column we'll have to trigger 
// a re-sort of the databrowset since LEpdateDataBnowserltems 
if does not trigger this. 

// 

DataBrowserPropGrtylf} aortProperty ■ 

ThrowIfOSErrt 

GetDataBrowaarSortProperty(nBrovser» 
iaortProperty )}i 

if ( sortProperty = kCompletedColuimi || 
sortProperty = kPercentageColumn } 
ThrowIfOSErrC 

SortDataBrowSGrContainer[ 

inBrowaer, kRootltein* true)); 

1 

elae 

i 

// don't aJlow the checkbox for container items to be 
if modified by the user This is done by fust reluming 
a false from this call, which will be translated into 
// the correct error code by our entry point member, 
return false: 

I 

return true: 

1 

J 

return false: 

I 

There’s not much to say about the main entry point 
function, except that it returns a special error code 
errDataBrowserPfopertyNotSupported for properties that we 
don't supply (i.e* if OnGetItemData or OnSetitemData 
return false), 

In the OnGetItemData member function, w'e first handle 
three predefined properties: the “is editable” property, 
telling databrowser that all of our items are editable, the “is 
container” property, where we decide whether an item is a 
container based on whether our internal item 
representation has child items or not, and finally the 
property named kDataBrowserltemSelfldentityProperty. This 
one is requested in column view mode for the regular 
display. Column view mode has a fixed display style of 
icon+text except for the preview area, which is a custom 
content type. So, when in column view mode, we’ll display 
an icon in addition to our item's title. Since 1 was too lazy 
to design some icons, 1 chose to use the clipboard item for 
plain task items and a folder icon for task groups (i.e, 
container items). The code then continues to the 
kTitleCoiumn property, which will stuff the column title into 
the DataBrowseritemDataRef. 

The DataBrowseritemDataRef type Is a reference to an 
opaque container that is used to transport the data to and 
from the databrowser. There are a number of different 
setter and getter functions that allow you to store and 
retrieve various types of data (e.g, 
Get/SetDataBrowserltemDataText for CFStringRef). Usually, 
databrowser only accepts one specific data type for a 


given property (e.g, a CFStringRef For text properties), 
with the exception of the icon+text column type, which of 
course allows you to specify both an Icon Ref and a 
CFStringRef, Also, for progress bars and relevance ranking 
bars you have to specify a minimum and a maximum 
value in addition to the actual value. 

When looking at the code for 
ToDoListWindow::OnSetltemData, you’ll notice quite a few 
calls to UpdafeDataBrowserltems. ITiis is because some of 
our properties are actually related: the checkbox column is 
just a Boolean (well, not quite, it may have three states) way 
of displaying the information that is also presented in the 
progress bar column, namely the progress of the task. So 
when a checkbox is toggled, we also have to update the 
progress bar and, of course, since the containers’ progress is 
calculated by summing up the progress of their child items, 
we also have to update all the enclosing containers’ 
checkbox and progress bar properties. 

This calculated progress value for containers is also 
the reason why we don't allow the user to toggle the 
checkbox for a container item. By returning false from this 
member, our entry point will return 
errDataBrowserP ropertyNotSupported to databrowser, which 
indicates that we didn’t allow modification of this 
particular piece of data. Databrowser will then again use 
the itemData callback (in it's getter variant) to query the 
correct data for this property and redraw the cell. 
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The other thing to note about this function is that 
when a checkbox value is changed, we'll trigger a re¬ 
sorting of the databrowser. Databrowser by itself does not 
change the sort order w'hen the user edits values in the 
sort column (at least not in the current implementation). 
Depending on how you are using databrowser, 
rearranging kerns immediately might not be what you 
expect, so this is left to be done manually In our case, we 
want to have completed tasks to be sorted properly even 
after editing, but you’ll also notice that this may be rather 
disturbing as they move immediately after you toggle a 
checkbox, making it impossible to toggle this checkbox 
again without starting a search for your item. While this 
may be feasible for a to-do list, in general this behavior 
may confuse the user. 

Notification callback 

Next, let's have a look at the item notification callback. 
The sample code only handles the single notification 
required For hierarchical datahrt)wsers: the “container 
opened’’ notification. Whenever this notification is sent, the 
items inside the c'onlainer have to be added to the 
databrowser, Since our ToDoltem object contains a list of all 
its child items, this is fairly easy 

The last parameter to this callback, the 
DataBrowserltemDataRef, is not currently being used, but 
allows the flexibility to pass more detailed information about 
some notifications in the future. 

Listing 4 shows the item notification callback (of course, 
there is also a static member function serving as the main 
entry point for the callback - just like with the item data 
callback, which just dispatches to this regular member 
function for convenience): 

Listing 4: Item notification callback 

ToDoLij^t Window:: Qnltem Noti ficaiion 

Callback for notlficaiions from databrowser. Handles only a single notification: 
"container opened" in response to which we ll fill the container with Ueins 

void ToDoListWindow; : OnlteiaNotificatiQn [ 

DataBrowserltemlD inIteralD. 

DetaBrowserltenjNotiflcation inMessage, 

DatalrowserltemDat aRef inOutIteaDat a) 

( 

switch ( InMessags } 

[ 

case kfiataBrowserContalnerOpened: 

I 

// a container was opened -> add all the child items 
// 

ToDoIteni^ container ( 

this->ResolvaItemID(inItemID]): 

If ( IcantainerDchlldlteins.einpty() ) 

I 

std::vector<DataBcowserItemID> 
childItemIDs{ 

container'>Ghlldlteins. size ()) : 

// convert fromToDoliem object pointers 
// to DataBrowserltemlDs 
std: :transforDi( 


container->chlldltenis-begin() , 
container->chlldItems * end {), 
childltemlBs.begin(}, 
GetltemlD)j 

// add the items to databrowser and specify 
// that they are piesorted by their index 
ThrowIfOSErr( 

AddDataBrowserltems( 

ELBrovser, 

inItemID. 

childItemIDg*size[), 
fifchildltemlDs[0]. 
klndexColmjin)) : 

I 

] 

break; 

f 


This is our first encounter with the API used to add items to 
a databrowser: AddDataBrowserltems. This function allcws you to 
add multiple items simultaneously Wherever possible you should 
take advantage of this feature, as it allows databrowser to 
minimize the overhead for invalidating and updating. 

Also, the last argument is a property fD that tells 
databrowser how tlie items are sorted within the array you 
are passing. If this sorting matches one of your column 
.sort orders, pass that column’s property ID (in our case, it 
matches the index column’s sort order)- If the databrowser 
is currently sorted by that column, databrowser can use a 
slightly more efficient insertion algorithm. This doesn’t 
really matter in our example, since the number of kerns 
we add is usually not very large, but once you add a few 
thousand items, this may well make a difference. If the 
items aren’t sorted by any specific column property, just 
pass kDala Browser Item NoProperty. 

Keeping order 

So, how does databrowser compare items? 
Fortunately, the answer is: it’s up to you! Consider, for 
example, our index column: it is a text column where we 
pass a string representation of the item’s index to 
databrowser, Now, we all know that comparing strings 
that represent numbers doesn’t quite cut it: you’d usually 
get orders like ”1”, “10", '*2”,... so if databrowser would 
just sort by cxjmparing the strings we pass, this would 
produce a wrong result. 

Mowever, since we know the number representation 
for the index, it’s quite easy for us to perform a real 
number comparison. 

For that reason, databrowser uses the item compare 
callback to let you compare two item properties. Well, I 
probably should be a little more exact here: your callback 
determines the order relation between any two items. 
Databrowser just passes the current sort property ID as a 
hint on what you should compare. However, it’s totally up 
to you to define the order relation between the items, so 
if you chose to compare a different property, databrowser 
will happily display the items in that order. 
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Of course, in most cases, this would probably confuse 
the user, since they usually expect the items to be ordered 
by their visual representation when they chose a column 
to sort by. But it's just important to note that the property 
ID passed is just a hint as what you compare, but 
data browser does not rely in any way on the fact that you 
have to compare using exactly this property. 

Anc^ther fact I should probal^ly menticm is that the 
sort algorithm used by databrowser is a si a hie sort 
algorithm, which means that during sorting, if any two 
items are identical, they won’t cliange their relative order 
This allows the user to apply multiple sort criteria by 
sorting several times in reverse cirder of significance 
(applying the primary sort property last)j which partially 
makes up for a shortcoming of clatabrowser, namely the 
fact that it only knows about a single sort property instead 
of primary, secondary, etc. sort criteria. 

Well, let's have a look at ToDoLiscWindow's 
implementation of the item comparison callback (Listing 
5), The comparison callback should return a Boolean 
value, which indicates whether the first item is to be 
considered “less than” the second item. 

listing 5: Item comparis on callb ack __ _ 

ToDoUsiV;'lndow;:{:ompimIU:mii 

tiidliack l^)m databmwscr tu compare two items, (xiinpares using the native 
representation of the data. Reiijrns wheLher item 1 is ''less tlian'’ item 2 , 

bool ToDoListWindow:tComparaItems( 

DataLBfowBsrltemrD inlteniOne. 

DataBrowser ItemlD itiltenTwo, 

DataBrowEerPropectylD inSortProperty) 

ToDo Item * itetnOne ( 

this->RescilvertemID(inIte!iiOne]): 

ToDoItem* it emTwo( 

this->ResolVeitemID(initemTwo ))i 

switch C inSortProperty ) 
i 

case klndaxColnmn: 

return Getltenilndex(itentOne) < 

GetltemlndexCiteiaTwo); 

case kTitleColumn: 

re turn CF St rin gCompa re{it emOne->ti11e, 

IteniTwo ■ >title, 
kCFCorapareCaselnsensitive) ^ 
kCPCompareLessThan: 

case kContpletedColunm: 

c ase kP ercen t a geCo1umn: 

return ite 0 jOne'>GetCompletion{} < 

itemTwo->GGtCoiiipletiQa{): 

case kLastHodifiedColumn: 

return iteTnOne->inodificationDate < 
i t emTwo - >mod 1 f i c a t i 0 tiDa t e : 


] 


default; 

return inltetnOne < InltemTvo: //just *soniaihisg* 
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That’s it? 

So, these were the '"required” callbacks that enable 
databrowser display the items correctly. Of course, there 
are more callbacks one can supply, but I won’t be able to 
discuss them all in this article. The sample application 
implements a couple more callbacks to support drag & 
drop and help tags. Take a look at the source code for 
ToDoListWindow (in file ToDoListWindow.cpp) to see their 
implementations. 

If you want to support column style browsers in your 
application, you probably also want to implement at least 
the custom draw callback, so you can draw something 
into the preview area when a leaf item is selected. The 
example app also implements this callback and draws the 
untruncated Lille into the preview area. 

Gotchas & Tips 

Having shown all this, Td like to warn you about 
some of the pitfalls you might hit on your way: 

First, you should keep in mind that databrowser is a 
very complex control - it even automatically embeds 
other controls (e.g. the scrollbars) that you don’t know 
about. This might not affect you, but for some frameworks 
it might come as a surprise seeing a control they never 
added. Also, since the scrollbars are embedded inside 
databrowser, you might have a liard time passing events to 
the correct control if your own control hierarchy is not a 
true embedding hierarchy but nilher managed by your 
own framework. 

Make sure you have a root control in your Window: 
inline editing in databrowsers text columns won’t work 
unless the window has a root control. On Mac OS X, a 
root control is created for you automatically, but on Mac 
OS 9, youil have to create the root control yourself using 
the CreateRootControl APh 

Another pitfall is that databrowser is the first control 
to rely on the documented requirement that a GrafPorts 
origin must be {0,0} when calling ControlManager APIs. 
You’ll see all kinds of weird offset problems if databrowser 
is called with the origin set to something else using 
SetOrigin. Unfortunately, that’s what the current 
PowerPIant implementation doe.s to provide a local 
coordinate system for each pane. However, at the time of 
this writing, it seems like Metrowerks in working on a 
version of PowerPIant that gets rid of this limitation. 

When switching between list view' and column view 
style, you will have to re-configure your databrowser 
when switching back to list view' style, i.e. you have to 
add all your column definitions again, since once you 
enter column view style, databrowser forgets about the 
column configuration. Column view' .style cannot be 
configured, so switching to column view' style works 
without any extra work, but when switching back, your 
previous list view column setup is lost (the .sample code 
handles this, so you can have a look there). 


If you allow your users to toggle back and forth 
between list view and colunm view mode, it might also be 
a good idea to use the Get/SetDataBrowserUserState API to 
save and restore the user state as you leave resp. enter list 
view mode. Beware though, that Set DataBrowserUserState 
will only work after you have added all the columns that 
have been in there before - it won’t restore the columns 
themselves, just the user modifiable settings of these 
columns. 

If you are using databrowser in a dialog and the 
databrowser items do not allow user interaction while in 
background (i.e. no drag 8l drop), it’s probably a good 
idea to have the databrowser content dimmed when the 
control is inactive. By default, databrowser will only dim 
the header buiions, but not the content. You can achieve 
comeni dimming by calling S et Data B rows erActiva lie ms 
with the appropriate Boolean parameter. When passing 
false for the “active” parameter, all items will be 
considered inactive, regardless of their 

kDalaBrowserltemIsActive property After calling this API 
with true for the “active” parameter, the active .state for 
each item will be restored to what the item’s 
kDataBfOwserltemlsActive property specifies. 

Remember what I said earlier about consistent 
notifications? You’ll get into trouble when di.sposing your 
callback UPPs (or, if you use an object like in the sample 
code, disposing the object) before the databrowser 
control is disposed, since databrowser will attempt to 
send “item removed” notifications as it is disposed. To 
play safe, you may want to call SetDataBrowserCallbacks 
with a NULL parameter for the callbacks to reset them 
back, .so databrowser won’t try to access your UPPs. 

Be careful when specifying custom fonts, styles and 
sizes for the column headers: Keep in mind that 
databrowser on X has a fixed header button height that is 
given by the OS, so if your font settings increase the pixel 
size of the text, it might get cut off. 

To specify custom font style settings for the 
databrowser contents, use the regular SetControlFontStyle 
API. You may need to adjust the databrowser row height 
to accommodate larger pixel sizes of the characters. 

If you plan to incorpcjrate databrowser in your Mac 
OS 8/9 product, you should be aware tliat “ at the time of 
this writing - there is no complete API parity yet between 
databrow-ser in Carbonlib 1.3 and databrowser in Mac OS 
X lO.O. Apple plans to bring the APIs on par in a later 
release of Carbon Lib, so you may want to require that 
release (once it becomes available) if you want to create a 
single binary running on Mac OS 9 and Mac OS X. 

Conclusion 

Databrowser is a very powerful tool to display your 
data. It has been designed to be able to accommodate 
large amounts of data, but it’s also easy enough to 
manage, so it can be used even for small, flat lists of 
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simple data. This allows you to use databrowser as the 
display front end for any kind of list data your application 
needs to display. 

Whether used to browse a file system like hierarchy 
or as a front-end to your database, or even for a plain list 
a la ListManager, databrowser proves to be a scalable 
solution for many of these purposes. 

1 did some basic performance tests and found that 
databrowser has no problems whatsoever to handle 
lOOjOOO items (although it might be another question 
whether it makes sense to even allow' the user to browse 
through 100,000 items). 

Memory footprint should be relatively small (about 20 
bytes per item in total in the current implementation), so 
databrowser is a really scalable solution for applications 
that need to present data in a tabular form to their users. 

As mentioned in the beginning, using databrowser 
also saves you from the hassle of playing catch-up with 
Finder’s list and column views when trying to provide a 
consistent U1 experience to your customers. 

As we saw in the discussion of the sample code, only a 
few API calls are required to get your databrowser 
configured. By relying on the built-in display types, we could 
leave out any rendering or formatting code altogether {O.K., 
except for the index coluiiin, for which we created a 
formatted string representing the index' numeric value). Most 
of the code discussed was just item data exchange with 
databrowser. The ability to store your data in whatever 
seems the appropriate way (in our case objects of class 
ToDoltem ) enables you to write much more readable code as 
you don’t have to write code that will access databrowser's 
internal data, potentially having to use heavy casting. 


Starring from either the sample code for this article 
which is available by FTP or from the BasicDataBrowser 
sample code that comes with the Carbon SDK, you should 
be able to start test driving databrowser and see how it 
fits into your application. 

Where to Go From Here 

Make sure you take a look at the DataBrowser 
Technote TN 2009, available at 

<http://developer.apple.eom/technotes/tn/tn2009.html>. It contains 
valuable information about the databrowser APIs. 

Also, check out the sample code section cjf the 
CarbonSDK: there’s a "BasicDataBrowser'' sample which 
also shows how to create a simple browser (although 
some of the features in the sample aren't yet wired up as 
of this writing) as well as an implementation of a 
LDataBrowser PowerPlant class. 

Another valuable source of information for me has 
been the Carbon Development Mailing List 
<http://lists.apple.com/mailman/llstinfo/carbon-development>. 
Quite a few developers on this mailing list have started to 
use databrowser and are walling to help others with their 
problems. 

Documentation on the Carbon Event Manager (and 
Carlx>nEvents), which is used exclusively to drive the satnple 
app, is available at 

<http://developer.apple.com/techpubs/macosx/Carbon/oss/ 

Carbon£ventManager/carboneventmanager.html>. 

Special thanks tojim Rodden for remewing this article 
and answering many of my databrowser related questions 
on the Carbon Deveiopmenl mailing list. Also, thanks to 
Martin Bestmann for reviewing the article. B 
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by Wilfredo Sanchez 


DropScript 


Or How to Build a Way Easy Yet Spiffy App 


Quick, 1 Need A Demo 

Last year at Apple’s Worldwide Developers Coofeience I was 
giving a talk on BSD in Mac OS X. Basic'ally^ I was standing in 
front of a (full) room of Macintosh developer acplaining why 
Unix is good for Mac OS, 

There has been a lair amount of debate over the value of 
keeping the BSD cT^mmand line (Terminalapp) and the BSD 
toolset in the base operating system. The majority of Mac OS 
users will not need tf> interact with the a>mmand line, and 
therefore the Terminal will not he of great use to them. (There is 
also the argument that the very presence of the command line 
option in the system will give developers an undesireabie crutch; 
that users might end up having to use the command line.) 

I actually agree that Terminalapp is not a necessity in the 
base system, though Im glad it's there for my own convenience. 
(It is a necessity in the developer toolset.) I also agree that 
requiring users to deal with the decidedly arcane Urdx interface 
would be a grave mistake. However, even with no way to get to 
an interactive command line, the presence of the BSD toolset in 
the standard installation of Mac OS is of great vakte to 
developers and therefore to users. My argument is simple: the 
BSD commands provide anodier valuable API to developers; 
they enable software authors to do great things will less effort. 

In order to make my case tliat the BSD toolset is impcjrtant, 
it helps to have a good demo for the talk, in true WWDC lashic^n. 
Certainly 1 can’t let the QuickTime folks get all of the applause. 
BSD provides many small programs (often called commands, as 
tliey tend to be invoked by users on an interactive command 
line), each of which performs some specialize function. A 
ct)mniand called cp, for example, c'an copy a file; anotJier, mv, 
can rename a file. An application author C’an write programs that 
invoke BSD c'Ommands to do certain task. These commands can 
he shell scripts whic:h in turn may invoke several other 
commands in sequence. I figured that an application that did this 
would be a good demo. 


I had heard of an application for NeXTStep (can't remember 
the name; IVe never seen it), which would let you graphically 
create a shell script by chaining commands together. That 
sounded hard to write in a week... I’ve seen people use 
MacPerl, which lets you create droplets, applications onto which 
you can drop a file and have a perl script prtxiess the file for 
you. Now wouldn’t it be cool if you could take any BSD 
command and turn it into a drop appiicadon? That didn’t sound 
so hard, so I started thinking about it. 

Designing A Suhpiusingly Simple Appucation 

What I needed w^as an program that could turn a 
command line tool into an application. Many command-like 
tools operate on files. You invoke the program by name and 
give it file names as arguments. For those of you not familiar 
with the command line, the basic usage is fairly simple. Say 
I have a program called gzip, which will compress a file. I 
want to compress the file Big File, so I type the following into 
the terminal: 

gzip “Big File’* 

and I end up with a smaller file called Big File.gz (the .gz file 
name extension denotes a gzip-compressed file). Now I want 
to be able to do the same thing in Finder by dragging a file 
onto an icon rather than using the command line. 

My droplet-generating program therefore needs to create 
a new application which invokes the desired command 
(typically a shell script)! for me, with my file as an argument. 
I started by writing a droplet application which I w^ould use 
as a template, thinking that the droplet generator would copy 
the lemplate application and replace the command it invokes 
with another. 1 wanted to avoid the need to compile a new 
binary, since many users will not have the developer tools 
installed; while ifs probably OK to say only developers can 
create droplets, Fd rather not require the developer tools if 1 
don’t need to. 


Wilfredo S^chez <wsanchez@mit.edu> is an engineering manager at Know^Now; Inc., www.knownow.com, and know^ just enough about Cocoa 
programming lo hurt himself and px>ssibly others. 
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Writing the primordial droplet 

My plan was to create an application which would 
contain a shell script in it. Whenever the application is asked 
to open a file, it will invoke the script with the file's path as 
an argument. The generator would therefore only need to 
copy the original app and replace the script with a new one. 

1 decided to write the application using Cocoa, Mosdy, this 
is tecause Cocoa is the only application toolkit I’m proficient at 
(I don’t write many apps), but the reason Cocoa is the only 
toolkit 1 know is that Cocoa is an excellent toolkit. Cocoa does 
an excellent job of mimmlzing the amount of work 1 need to do. 
For example, when a user drops a file onto an application with 
Finder, what happens is that Rnder laimches the application and 
sends it an AppleEvent telling it to open the file. Any decent Mac 
OS application which opens files has a File menu with an Open 
menu item which also opens a file. Cocoa automatically provides 
menu items for quitting, hiding the app, hiding the other apps, 
as well as the Edit functionality of copy and paste. 

1 start by creating a new Cocoa Application project in 
Project Builder In the resources group of the project, J add an 
new empty file called “scripC which will contain my shell script. 
We 11 start with a simple script: 

/blQ/sli 
gzip -9 

This script will compres.s files with gzip using the maximum 
compres,sion levef 

Most Cocoa applications instantiate a controller object. This 
object reacts to user actions and drives the application. Very 
often the cxmtroller is “owned’' by the main user interface; HI dtj 
that for this app, but more on that later First, Fll cx)asider what 
the controller needs to do. 

For this app, I already know that it needs to be able to 
open a file, so fll define a method called open:, open: is what 
is called an action; actions are methods which are called by 
other objects in the AppKii to trigger some activity in the 
application. AppKit interface elements can be set up to invoke 
an action on another object, called its target. For example, 
pressing a button (^r sliding a slider will cause the button or 
slider to send an action to its target. Action methods always 
take one argument: the id of the object which sent the action 
message to the target. The interface for our controller object 
(which I'll call a DropControlier) follows: 

ffiiflport (Foundation/ KSObj ect * h> 

@class NSStrlng; 

^interface DropControlier : NSObject 

/* Insiiuicc variabJes 7 
tl 

/*ACdOD!v V 

■ (IBAction) Qpsa: (Id) aSender: 

©end 

Next, 1 open up the MainMenu.nib file in the project, which 
opens in Interface Builder. 1 then import the header 


DropControllerh (click on the Classes tab, and use the Classes- 
>Read Files,., menu item), and instantiate that object (Classes- 
>lnstantiate) in the nib file, 'When the application is launched, 
the MenMenu.iiib interface (which is the main application 
interface) is loaded automatically It will in turn instantiate the 
DropControlier object* 1 want the FiIe->Open menu item to 
invoke the open; action method, so I simply connect the menu 
item to the controller and set the target method to open:. (You’ll 
be wanting to go through an Interface Builder tutorial if I’ve lost 
you; If you want to take my word for it, this is very easy.) And 
because I won’t be needing them, 1 can delete all of the menu 
items other than the Apple menu and the File->Open item. 

If you aie new to Interface Builder, that was the hard part. 
The test Is a breeze from here. 

I need to locate the path to the shell script (or a^mmand) 
I've put into the application (ifll be in the Resources folder within 
the app), so I'm going to keep that uifonTiation in an instance 
variable of the cx^ntroller. 1 therefore edit DropControllerh to add 
an instance variable: 

/* Ijisiance variables V 

[ 

©private 

NSStrtfig* BiySctiptFileHaEtte: //well keep the to the script 
I 

Side note: I make a habit of always iriLirking my instance 
variables as private, as allowing other objects to access them 
directly is almost always a mistake, Sulx:lasses cannot directly 
modify a private instance variable, instead, they must use the 
provided API, a core* tenet of data encapsulation. 

We can liegin writing the implementation of the comroller 
(DropControiler.m) now. 

^import (Foundation/Faundatioa. ti> 

#iniport (AppKi t/AppKit .h> 

^import "DropController^h'* 

©implementation DropController 

/* Inits 7 

- [id) init 

I 

if [(self = [super init])) 

I 

myScriptFileName = 

[[fNSBundle raainEundle] pathForResource:©"script"' 

ofTypeinil] retain]: 

1 

return self: 

1 

’ (void) dealloc 

I 

[myScriptFileNatiie release] : 

[super dealloc]: 

1 

/• Actions 7 
©end 

The init method initializes the instance variables, in this case 
setting myScriptFileName to the path to the script and retaining 
the string (marking it so that it isn’t deallocated until we are done 
with it). When the controDer is discarded (the app quits), the 
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ciealloc method releases the string (expresses the controller's 
sudden disinterest in the string's safety), Andrew Stone discussed 
the use and power of NSBundle in his article “Dynamic Btindles 
and Runtime Loading in OS X" several issues back. 

And then I tell the controller how to open a file by 
implementing the open: action: 

/* Acii«ns 7 


- (void) runScriptWithFlles: (NSArray* ) aFlleList 


1 


[NSTask launchedTaskWithLaunchPatk: TnyScriptFileMarae 

arguments: aFileListJ : 


- (IBActlon) open; (id) aSender 
I 

NSDpenFanel* anOpenPanel = iNEOpenPartel openPanel] : 

if f [anOpenPanel runModalForTypes:nil] = HSOKButton) 

1 

[self runSctiptWithFiles: [anOpenPanel filenames]]: 


The open: method creates an open panel and runs it 
modally, then runs the script on the selected files. I put the 
actual code to run the script in its own methcid because Lll 
be needing it again later 

At this point, 1 have an application which 1 can launch, 
then bring up the File->Open menu, and have it run a script 
on a file (or a few files) for me, Bui I still need to handle 
AppleEvents from the Finder or other sources, AppKit makes 
this easy. The AppKit application object (which I am using 
already, though I’ve not had to know it yet) handles 
AppleEvents For me. All I need it to ask it to tell me when it 
gels an open message. 

First, I go back to the MainMenu.nib in Interface Builder, 
We need to mark the controller object as the delegate of the 
application object, A delegate is an object to which another 
object sends specific methods when something interesting 
happens. In Interface Builder, we connect the File’s Owner 
object (which, for MainMenu.nib is the application object) to 
the controller object as the delegate. 

If the application's delegate implements the method 
application:openFile:, the application will automatically call 
that method whenever the application is asked to open a file, 
such as with an AppleEvent. (This and other delegate 
methods are documented in ihe NSApplication docs.) All I 
have to do, then, is implement the method: 

/* Application delegate V 

- (BOOL) application: {NSApplication*) anApplication 

openFile: (NSString*) aFileHatite 

( 

[aalf runScriptWithFllEs■ [NSArray arrayUithObject: 
aFileName]]: 

return YES; 

1 


Now dropping hies onto the droplet’s icon works! With that, 
Fve finished up the prototype droplet, which can compress files. 


Writing the droplet generator 

The droplet generator should itself Ixf an application, so that I 
do not need acress to the terminal. In fad, fd like to be able to write 
a shell script in Text EdiL and then drop that file onto my dioplet 
generator Thai i% the droplet generator iLself should fx? a droplet. 
Well,., huh... T just wrote one of tliose. All this dnjplet needs it) do 
dififerent Is that instead of compre.ssing a file, it needs to copy die 
prototype app and replace the shell script inside. Well., huh... 1 can 
do that w'ith a shell script a lot more easily that in C (even Objective- 
C) cxxJe, So it seems all \ have to do here is replace the g?ip script 
with a script that copies the application (itself!) and puLs the new 
script in the right place. The droplet generator iteself becomes the 
prototype droplet. (Being lazy, like most programmers, this was an 
exciting revelation,) A simple script to do this might look like this: 

ffl/bin/ah -e 
ScriptFileNarae^$l: shift 

BropScrlpt='*S (echo $0 | sed 's j \ .app/, *$ | \ ,app | ') " 
Destination^^ (dlrname ^(ScriptFileNaine I ”) 

Droppe.i:Nffiiie='''DtCJp''$ (baaename "$ (ScriptFileName \ ” 

I sed 's/V-.^S//') 

NewDropper^-SlDestination I / $ [DropperNante] *app’' 

dkdir [NewDcopperl" 
pax - rw . '■ $ I NewDroppe r ] ** 

cbmod u+w "$ [NewDroppeF]/Contents/Hesources/script** 

Cp -f '■5[ScriptFlleName]" 

[NewDropper]/Contents/Resources/script” 
chmod 555 "$|NewDropper)Zcontents/Resources/script" 


For more information 

The complete source code to DropScript is available via the 
Darwin CVS server at Apple, in the DropScript CVS mtxlule. You 
can dowtiJoad a pre-built executable from my home page at MIT 
at http://wvvw, mit.edu/people/wsanchez/software/ 

These are a few features in DropScript which were omitted 
from this article for simplicity, such as: 

• The primordial shell script is acaially more complicated, as it 
does some rudimentary error checking. 

• In order to emulate the behavior of Stufflt Expander, wliich is 
probably the most familiar drop application for Mac OS users, 
I added a little code to have the droplets quit after processing 
a file if they wererit otherwise already running. 

• There is now a mechanism by winch you can specify the file 
types that your new droplet accepts within the shell script. 

• There is an about box and a useless preferences panel. 

Some commands don't take file names as argumeoLs and most 
command have some special options you might want to use. The 
most flexible way to create droplets would therefore be to write a 
shell (or perl/python/etc) saipt that takes file name argumenis and 
invkoes the right commandCs) with the right optionCs), and use that 
script as tlie command In your droplet. K1 
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POWERPLAMT 

WORKSHOP 


By Aaron Montgomery 


Basic Dialogs 


How one goes about writing a 
PowerPlant application 

These Articles 

This is tht- fifth iirtide in a series of articles about 
Metrowerks' PowerPlant application framework. The first 
article introduced how the framework deals with commands, 
the second article discussed the deliugging facilities of the 
framework, the third introduced windows, and the fourth 
article tacked file classes. This article completes the 
discussion of the core of PowerPlant by discussing the way 
PowerPlant handles dialogs. This series assumes familiarity 
with the C++ language, the Macintosh Toolbox API and the 
CodeWarrior IDE. The article.s were written using 
CodeWarrior 6 with the net-update to IDE 4.1.0,3 and no other 
modifications. Throughout this and future articles, I will 
assume that you are using the class browser and the 
debugger to explore the PowerPlant code more fully 

Broadcasters aihd Listeners 

We have talked about the command chain that PowerPlant 
uses to convert menu selections to code calls, but trying to 
pass all of the user interaction with a dialog box through this 
chain w^ould be cumbersome. Fortunately PowerPlant offers 
an alternative method of linking different classes together 
through its LBroadcaster and LListener classes. Each 
LBroadcaster object keeps a list of LListeners and can 
broadcast a message to the objects in its list. The broadcast is 
done by calling each LListeneds ListenToMessageO method. 
This method takes two parameters. The first, of type 
Message!, describes the message lieing broadcast. The 
second, of type void*, allows the LBroadcaster abjeci to pass 
message specific data to the LListener object. 

Although this article focuses dialogs, the LBroadcaster 
and LListener classes can also be used in other places. For 
example, the LGrowZone class (mentioned in the second 
article) broadcasts a message when it needs more memory. If 
you have a class that can release memory in a pinch, you 


might want to make it an LListener and register it with the 
LGrowZone object. 

In the case of dialogs, the control classes are 
LBroadcasters and will broadcast their message whenever they 
are adjusted. This means that if you want something to 
happen when a control is adjusted, you can create an 
LListener and have it listen to that control. This means that 
much of the code for dynamic effects in dialogs can be placed 
in separate classes and linked to the dialog before it is 
presented to the user. 

Constructor 

Before kx>king at the Tescxiice file, you may want to run 
HTMLedit and play with the amirols in the dialog (select 
Preferences... from the Edit menu). New gp to the IDE and double¬ 
click the AppResources ppob file (which .slK>uld open in G>astructor). 

The Preference.s dialog has two LPushButton.s (OK and 
Cancel), an LMultiPanelView (where everything important 
happens) and an LTabsControl (to switch between the panels). 
The two LPushButtons did not require much set up, but you 
need to remember to let the LGADialog know the button IDs 
for the default and cancel buttons. The LTabsControl needs to 
have a valid Value Message, 1 set the value to SwPa for 
Switch Panel. This is the message that will be broadcast when 
.someone clicks on the control, The LTabsControl needs to 
have an associated tab# resource which determines the titles 
of the tabs (as well as icons, if any are used on the tabs). 
Unfortunately 1 do not think the tab# resource can be edited 
in Constructor. You have two choices: add it to the 
AppResoufces.rsrc file or open the AppResources.ppob file in 
Resourcerer or ResEdit. If you choose to keep the tab# 
resource in the AppResourcesjsrc file, you will not see the tab 
names in Constructor. Because I like to see these while 
working on the dialog, I added the tab# resource to the 
AppResources.ppob file with Resourcerer. 

Now to the centerpiece of the dialog: the 
LMultiPanelView. To add panels to a LMultiPanelView in 
Constructor, you select the Panels cell in the Property 
Inspector window and then select New Pane! from the Edit 


Aaron teache.s in the Malliematics Department at Central Washington Unwersity in Ellensburg, WA. OuLside of hLs job, he spends time riding his 
mountain bike, watching movies and entertaining his wife and two sons. You can email him at montgoaa@cwu.edu, try to catdi his attention in the 
new.sgroup comp.sys.mac.cxip.powerplant or visit his wel> site at mac6910B.mathxwu.edu:8060/. 
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menu. In this case, there are three (one for each tab). You 
tlien select which PPob resource to associate with each panel 
In our case, we use resources with IDs 10031, 10032 and 
10033 . The final settings which need to be made for this 
resource are the setting of the Switch Messag© {it should 
match with the LTabsControl) and selecting the Listen To 
SuperView checkbox. The LMulti Panel View is an LUstener 
and when it hears the Switch Message, it will switch to 
another pane!. Selecting the Listen To SuperView checkbox 
adds the LMultiPanelView object as a listener to the 
LTabsControl object. 

Now it is time to construct the three views that will 
appear in the LMultiPanelView. The first is used for 
determining the file creator of saved files. This LView was 
created by dragging an LVIew from the Catalog window into 
the AppResources.ppob window and then changing its 
Resource ID to 10031. The size of the panel needs to be 
adjusted to fit inside the LMultiPanelView. The Visible 
checkbox needs to be deselected (otherwise, all of the LViews 
will appear at once in the LMultiPanelView). The primary 
control here is a LRadioG roup View and four LRadioButtons. 
Since there is no need for the hutions to broadcast a message 
when they are hit, they do not need Value Messages. 
However, since the code will need to know which button is 
selected, the Pane IDs need to be set. The Pane IDs match 
the appropriate creator code for each application. Notice that 
there is an older LRadioG roup in the Other tab of the catalog. 
This has been replaced by the LRadioGroupView in the Views 
tab. 

The second LVrew (Resource ID 10032) used in the 
LMultiPanelView is very simple and straightforward. One way 
to save a little work is to duplicate the LView with Resource 
ID 10031, renumbered it to 10032 and then deleted all of the 
controls. This means that the new resource will be the correct 
size and visibility. This LView has an LStaticText and an 
LEditText. The LEditText is given a Pane ID because we will 
need to be able to access its contents from the code. The 
LEditText is from the Appearance tab and replaces the 
LEditField in the Panes tab. 

The third LView (Resource ID 10033) is the most 
complicated. Again, creation is done by duplicating the LView 
with Resource ID 10031, changing the Resource ID, deleting all 
the existing controls and adding new ones. It has an 
LPopupButton and an LMultiPanelView. The Message Value for 
the LPopupButton is SwPa for Switch Panel. The MENU 
Resource ID is set to 1002 (you can find this resource in the 
AppResources.ppob file as well). The LMultiPanelView uses 
Resource IDs 10034 and 10035. The Switch Message is set to 
SwPa so that it is consistent with the LPopupButton. Unlike the 
first LMultiPanelView, this one cannot simply listen to its 
SuperView and we will examine the code needed to link the 
LPopupButton to the LMultiPanelView below. Resources 10034 
and 10035 are very basic, consisting of some LCheckboxes and 
LStaticTexts, The LCheckboxes have had their Message Values 
set because the code will need to listen for their broadcasts. 


This concludes our tour of the AppResources,ppob file and 
we now turn our attention to the source code. As you build your 
interface, if you cannot find a control by browsing through the 
Catalog window, ask on the comp.sys.mac.oop.powerplant 
newsgroup. Usually someone will be able to tell you where it is 
in the Catalog, suggest a class from the PowerPlant Archive (at 
Metrowerks' web site), or provide a work around. 

Preference Class 

The CPreferences class handles the application’s preferences. 
The class consists of a constructor; a destructor; a method to 
register used classes; a method to set the preferences via a 
dialog; and a method to alert other classes about a change in 
preferences. We begin with the constructor. 


CPreferencesO ia CPreferences.cp 

CPreferences::CPreferences() 

: inyFile(StrlngLiteral_(*‘Emedit Ptefs“')) 

{ 

niyFlle. OpenOrCreateReso’urceFork (f sRdWrPerin 
OSType_Pref_CrGator, 

OSTyp e_F re f_Fi1eType, 
smSystemScript): 

I 

StNewResotirce tbePrefs {ResType_Pref, 

ResIDT^Pref, 
si^eof(SPreferences)); 
if(!tbePrefs.ResourceExlsted()) 

( 

EFref&rences* thePrefaP 

= rGinterprEt_cast<SPreferetices*> ( 

‘thePrefE.mResourceH); 

thePrefsP->FileType ^ 0SType_Default_Creator; 
thePrefsP->Marker = char_Default_Marker: 
thePrefs P->LinkUs eaTarget 

- bool_Defanlt_LiiikUsesTarget; 
thePrefsPOlraageUsesAlt = bool_Default_rmagetJseaAlt j 
thePref sP -) ItnageUsesEorder 

= bool_Default_IniagetJaGsBorder: 

thePref s. SetResAttrs {resLiOcked + reaPreload) : 



myPrefsH = relnterpret_cast(SPreferences* 

::GetlResource(ResType_Pref, ResIDT_Pref])3 
if (myPrefsH =“ nil) 

I 

Throw!fResError.O ; 

ThrowIfNil_(®yPrefsH); 

! 

UpdateO ; 

1 


The data member mypile is of type LPreferencesFiie. This 
class is provided by PowerPlant to create preference files in 
the System folder. In this case, the code names the preference 
file HTMLedit Frets and then opens the resource fork (creating 
it if needed). 

The StNewResource class will attempt to open the specified 
resource and if it does not exist, it wiU create the resource. The 
Resource Existed 0 method of that class will return false if the 
resource is new and in this case, the c’ode fills the resource with 
the default preferences. The code also sets the resource 
attributes to preload and lock the resource since we wiU want to 
have it available at all times. The resource structum is small and 
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SQ it is unlikely to cause an undue memory burden hene. When 
the StNewResource passes out of scope, the resource will be 
written into the preference file. 

Next the code loads the resoLirce and then passes all of the 
preferences to those classes using them. IVe decided to use a 
raw resource as a data member instead of using a StResource. 
This means that the code needs to call ::ReteaseResource() in 
CPreferences' destructor 1 felt that there was no need to use a 
stack class to handle memory management because the resource 
will be loaded until the application quits. If you ate going to add 
a resource data member to a class in other situations, you should 
consider using the StResource class instead of a raw resource. 

The most interesting method in the CPreferences class is the 
Set() method which runs the dialog. We present the code for this 
method now. 


SctO from CPrcfetiences.cp 

void GDocumentApp::CPreferences;:Set () 

StDialogHandler theHandler{PPob_Prefs, 

LCorunander: iGetTopCoinmander ()) ; 

LWlndow* theWindowP = theHandler.GetDialogO; 

LMultiPanelView* theMPViewF “ FindPaneByID_[theWindow?, 

PPob.PrefOPV, 
LMultiPanelView ); 

thefiPVlewP ■ >CreateAllPanel3 () ; 

LRadloGroupView* theRadioGroupP = 

FiTidPan6ByiD_ (theWindowF, 

PPob_PrefB_FlleType. LEadioGroupView); 

theRadioGi:oupP->SetCurrentRadiolD({**niyPref3H) .FileType) ; 

LEditText* theFieldP = FindPaneByID_(theWindowP, 

PFob_P i: ef a„Ma rke r, 

LEditText): 

LStr255 theMarker = ‘^nyPrefsH] .Marker: 

theFleldP->SetDencriptor(theMsrker); 

theMPViewP = FindPaneByID_(tbeWlndDwP. 

PPob_Prefs^HPV2, LMultiPanelView): 
theMPViewP’>CreateAllPanels(): 

LPopupButton^ thePopupP ^ FindPaneByID_(theWindowP. 

PPoti_Pref s^Popup, 
LPopupButton): 

thePopupP->AddListener(tbeMPVlewP): 

LCheckBox* theCheckBoxP “ PindPaiieByID_(tbeWindowP. 

PPob_Prefs^LinkTarget. 
LCheckBox); 

theCheckBoxF ’ >SetValne {(*'"layPrefaH) .LlnkUsesTarget} : 
LStaticText* theStatlcTextP = FindPane£yID_{theWliidowP. 

PPob_Prefs.LinkTemplate * 
LStaticText): 

CDynamicLinkText theDynaniicLinkText(theStaticTextP. 
theCheckBoxP]: 

/Aimitted code setting up other pand 

theWlndowP->Show(): 

while (true) 

[ 

MeasageT theMessage = theHatidier.DoDialog() : 
if [theMessage msg^Cancel] 

{ 

return: 

else if CtheHessage Tnsg_0K) 

1 

break: 


I 

1 

(*•myPrefsH).FileType “ 

theRadioGroupP ’ >GetGurreiitRadio ID (}; 

theFieldP “ FlndPaneEyID_(theWindowP, 

PPob_Prefs_Marker, LEditText): 

theFieldP->GetDescrlptor(theMarker): 

(* *TnyPrefsH) .Marker “ theMarker [1] ; 

//omitted code updating preferences handle 

: :ChangedResource{reiiiterpret_cast<HaTidle>(jnyPref3H)): 

r: UpdateResFile {myFile .GetResourceForkReftJumO ): 

UpdateO ; 

I 

Although it looks like a lot of code, there are only four 
basic steps. First, set the values of the controls based on the 
current preferences. Second, set up the dynamic text Third, 
run the dialog box. Fourth, update the preferences based cm 
the user interaction. 

The StDialogHandler class was introduced in the third 
article and one is used here. The first parameter is the 
Resource ID of the dialog and the second parameter is the 
super commander of the dialog. Since we will need to adjust 
some of the user interface before presenting the dialog to the 
user, we use the GetOialog() method to obtain the dialog 
window. We now look at the interesting bits of the code. 

The call to CreateAllPanels() is important because we will 
want to access the panels prior to user interaction. If you do 
not call this, the panels of the LMultiPanelView will be created 
as the user switches from one panel to another. If the panels 
were completely static, this approach would be appropriate. 
Because we are going to adjust each panel before presenting 
it to the user, It is easiest to adjust everything before starting 
to interact with the user. 

The next call that is new' is the call to AddListener(}. This call 
links the LPopupButton in the third panel to the LMultiPanelView in 
the third panel. Both the LTabsControl class and the LPopupButton 
class pass the tab or item number chcjsen as the void' parameter 
in their call to ListenToMessage(). This Ls exactly what the 
LMultiPanelView class expects and so there Ls no need tor any 
additional code to make the LMultiPanelView objects work. 

The line creating a CDynamicLinkText object will be 
explained below. What is convenient is that in thi.s rade, simply 
the creation of these objects is all that is necessary to generate 
dynamic effects in the dialog. The actual code to do that work 
does not need to clutter up the code handling the user 
interaction with the dialog. 

Next we show the window and let the StDialogHandler 
object run the dialog. The return value from DoDialogO will be 
the last message broadcast by an LBroadcaster in the dialog box 
(the StDialogHandler is an LListener that listens to the controls in 
the dialog). The only two messages we need to concern 
ourselves with are the msg_Cancel and msg_OK, all the other 
messages are handled by other LListener objects. The remainder 
of die axle is straightforward, we obtain the values from the 
dialog and update the preferences. 
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We will not discuss the Update() method but its code is 
straight forward (calling a number of methods to update the 
user preferences in those classes that use them). We now turn 
our attention to the CDynamfcLinkText and CDynamicImageText 
classes. 


CDynamicXip^kText & CDynamicImageText 

These two classes are responsible for dynamically updating 
LStaticText objects in the dialog as the user checks and unchecks 
LCheckBox controls in the dialog. The two classes are almost 
identical and we present CDynamicLinkText here. The code is 
below is presented as a testament to the ease with which these 
effects can be accomplished with PowerPIanC Other than the 
code to generate the actual text to be displayed, there are under 
10 lines of code in the entire class. 


(a>>^ninijcUnkTcxi code from CUynamicTcxLcp 

CDynamicLinkText:;CDynamicLinkTextt 

LStaticText* inTextP, LCheckBox* inUseTatgetP) 

: myTextPdnTextP}, 

inytlseTargetP (InUseTargetP) 

I 

myUseTargetP->AddListener[this); 

SetTextO ; 

1 

void CDynamicLinkText::LlstenToMesEage[ 

MeasageT inMessage* void* ioPatam) 

{ 

ioFatam “ ioParam; 

If [inMesaage = insg_ToggleTarget) ( SetText[): I 


SrOTLIQIIT 

seven times faster 


free demo 
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Code Fragment Support 
Leak Detection 
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void CDynamicLinkText::SetText() 

( 

LStr255 theTag ^ 
theXag += “<A hr:ef=\”": 
theTag += *•': 
theTag += 

if (myUseTargetP->GetVaLue{)) 

[ 

theTag "" target^\'''*; 
theTag +=* ’ -' j 
theTag += *‘\*'**i 

I 

theTag += 
theTag ; 

theTag += 
theTag j 

myTextF-> S etDe ec rip to r[theTag ): 
myTextP->Refresh(): 


CDynamicLinkText is an LListener and its primary method is 
the ListenToMessageO method. Its constructor accepts a pr^inrer 
to an LCheckbox and a pointer to an LStaticText. When the 
LCheckbox object is clicked by the user, it will broadcast a 
message. The CDynamicLinkText object will receive this me.ssage 
and upckite the LStaticText object to reflect the current settings. 

Other Classes 

Clianges needed to l>e made to the CDocumentApp class, 
CHTMLTextView class and the CTextDocument class in order use tliese 
preferences. CDocumentApp now handles the cmd_Preferenoes (and 
passes all of ilie wtjrk off to a static CPreferences data member). 
CHTlVILTextView and CTextDcKument now hold siatic data members 
for holding user prelerences as well as methcx^ls to ser and get this 
data. If yim want to view the actual changes yourself, search the files 
CDocumentApp.cp, CHTMLTextView.cp and CTextDocument.cp for 
comntenls starting wiQi //•. 

Concluding Remarks 

I havent a>vered every useful ct>ntK^l thuit can be placed in a 
dialog box but sliould have given you a feel for how to use 
Constructor to build the interface and the necessary code to run the 
interfac’e. You may have noticed that tills article is soniewliat shorter 
than previcxjs articles. The primary reason Ls that much of the code 
for this article has been used in pievicxis articles (in sllglitly odier 
contexts). At this point, 1 believe I have presented you widi the tools 
to build a basic Macintosh applic’ation using PcjwerPlani (and 
covered most of Tbe PdwerPlant Book topic’s in the process). Tm 
planning on taking a month hiatus but returning in October If you 
have a topic that you would like to see, please send me an e-mail. 

PowekPlant References 

For more on using the messaging system built into PtiwerPlant, 
you will want to read The PdwerPlant Book chapter "‘Controls and 
Messaging." There is also a ‘"Dialogs’" chapter in The PoweiRlant 
Book that covers (not surprisingly) dialogs. Another source of 
information is the source code of PowerPIant as well as the example 
files. I liave found tlie Appearance Demo and the Grayscale Sample 
to be particularly useful as they present a variety of different 
controls. You can also see more exatuples of dialogs in the 
StdDiabgs demo. K1 
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Making It Aqua: Adopting the 
Mac OS X User Experience 

Aqua and User Expectations for Mac OS X 


T he graphical user interface of the Macintosh which charmed 
so many people back in 1984 has come a \^ry long way. 
Indeed, with the recent introduction of Mac OS X, Apple 
unveiled Aqua, Aqua is the new interface that builds on the ease-of- 
use tradition of Mac OS 9, Aqua makes use of color, transparent 7 , 
and animation to enhance usability. It also delivers new behaviors 
that make using a Mac even more fun and satisfying for users from 
computer novices to professionals. 

With Aqua's revolutionary new features and attributes, users will 
expect your application to adopt and build upon its design. Why? 
Because people who use Mac OS X want all their applications—from 
spreadsheets and word processors to email clients and design 
tools—to have the consistency, appearance, intuitive design, and 
easeof-use characteristic of Mac OS X. Users know when a product 
doesn^t quite feel right (and so will product reviewers.) 

This article will help you understand what it will take for your 
application to meet these user expectations. 

Decide Where to Spend Your Resources 

The level to which you adopt Aqua will depend on many things, 
including your development schedule, market demands, competitive 
pressures, and resource constraints. I’he chart included here (see 
Fig. la) can help you prioritize your efforts. 

Look closely at Fig. la. The most important thing about this chart 
is focusing on compliance with Aqua basics before moving on to 
more advanced Aqua feature development. Spend your time becom¬ 
ing completely compliant with all the items under the "Good" Aqua 
Adoption Scenario (such as System Appearance, ad(}pting the Layout 
Guidelines, respecting the Dock, etc.) before spending any effort on 
the advanced features (supporting Sheets, Dock animation, etc.). 

What follows is a discussion of the individual building blocks of a 
“Good" Aqua adoption scenario. 

Create Quality Icons 

Your application's icon is one of the most visible attributes of your 
application on Mac OS X. A quality icon should clearly communicate 
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Rg. la- Aqua Adoption Scenarios 


what your application does, what type of media it works with, and 
whether it's meant for every day use. Just as you wouldn’t want a visual 
designer writing your code, developers should avoid designing icons 
unless they have a background in visual design. The latest "^Mac OS X 
Human Interface Guidelines” document (see next page) goes in depth 
on this and can provide you with a much better understanding about 
the incredible attention to detail icons have under Mac OS X* 

Respect the Dock; Location 

Your application should respect the Dock's location on the 
screen. When your application opens new windows, resizes win¬ 
dows, or zooms windows, it should avoid sizing them behind the 
Dock (or where the Dock is when it is visible). Sizing a window 
behind the Dock is extremely annoying because users are then 
forced to shrink the Dock or somehow move the window to get at 
its resize box. 


John Geleynse uforks in Apple's Wrldwide Developer Relations Technology Mamgement group and has experience in software development, product 
management, and product marketing Re promotes good user experience^related technologies within the Macintosh developer community. He can be 
reached atgeleynse@apple.com. 
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Respect the Dock: A Click on the Dock 
Should Always Open a Window 

Your application should always present a window when your Dodc 
icon is clicked. This is to eliminate the all-too-familiar case where a 
user closes a document window and thinks they’ve quit the applica¬ 
tion. The rules are straight forward: 

For document-based applications: 

If no document windows are open 

Open and create an untided document 
If all open windows are minimized 

Activate the last window minimized 
For non-document<based applications (e g. System Preferences) 
Show your main application window 

Comply with the Mac OS X 
System Appearance 

Aqua has a very unique, rich visual appearance which uses anti- 
aliased text, shadows, transparency, and color. On-scrcen interface 
elements have unique visual characteristics that go beyond what 
people are used to on the Mac or anywhere. AH of these characteris¬ 
tics are unique to Mac OS X and your application needs to adhere 
to the look of Aqua if if s going to feel as if it belongs on Mac OS X. 

Some common oversights in this area include white window 
backgrounds {rather than pinsU'iped backgrounds), mis-aligned pin¬ 
stripes, incorrectly sized controls, clipped buttons and static text, 
and the use of non-standard fonts and font sizes (rather than system 
and application font specifications). 

fliese types of oversights can dramatically affea the user's per¬ 
ception of the overall quality of your product. Do everything you 
can to ensure the visual presentation of your interface matches the 
appearance of Mac OS X. 

Adopt the Layout Guidelines 

Along similar lines, the appearance of Mac OS X also has a lot to do 
with the spacing and organization of interface elements. The “Mac 
OS X Human Interface Guidelines” document goes into great detail 
about layout guidelines. However, for the most part you don’t need 
to worry about memorizing all those numbers because Apple pro¬ 
vides a high-powered interface design tool: Interface Builder, which 
lets you design compliant dialogs and windows with ease. 

The Mac OS X layout guidelines were developed for readability, 
localizability, and future functionality. Compliance with them dra¬ 
matically affects the readability and usability of your Mac OS X 
application. 


Apple Help 

As pan of a “Good” Aqua adoption 
scenario, remember to provide 
user assistance in your application 
with Apple Help (and not your 
own help delivery mechanism.) 

“Better” and “Best” Scenarios: Sheets 

Sheets are a new feature of Aqua and one of the things frequently 
noticed by users. A sheet is simply a modal dialog attached to a par¬ 
ticular document or window, ensuring the user never loses track of 
which window the dialog applies to (and allowing the user to con¬ 
tinue working on other documents in the same application.) 

You should use sheets for dialogs specific to a document when 
the user must interact with the dialog and dismiss it before proceed¬ 
ing with work. Some examples include: a modal dialog specific to a 
particular document (such as saving or printing), a modal dialog 
specific to a single-window application that does not create docu¬ 
ments, or window-specific dialog typically dismissed by the user 
before proceeding. 

Don't use sheets for dialogs that apply to several windows. 

Sheets are intended to be used in situations when a particular dia¬ 
log is associated with only the window to which it is attached. 

Sheets are not appropriate for modeless operations where the dia¬ 
log should be left open to allow the user to observe the effects of 
changes applied. Such tasks are better suited to modeless dialogs, 
utility windows (palettes), or drawers. 

Also, please don’t use a sheet on a window that doesn’t have a 
title bar since sheets should emerge from a definite visual edge. 

Native Code Is Nice, But Not Enough 

Remember that finishing your port to Mac OS X doesn't mean 
you've finished your Mac OS X product. Delivering a good Mac OS 
X product obviously involves native code but, most importantly, 
includes paying attention to the details outlined in Fig. la. Native 
code is just the first step in bringing your application to Mac OS X. 

other Aqua Topics 

More on the topics discussed here (and others) can be found in both 
the “Mac OS X Human Interface Guidelines” document and the main 
User Experience web page located at bttp:jldeveU}perMppie.comlue. 
Look online for the latest version of the “Mac OS X Human Interface 
Guidelines,” and for links to Carbon- or Cocoa-specific documenta¬ 
tion and sample code for all of the topics covered in this article. 

Continued on page 49 








New Mac OS X 
Related Releases 

The following software is available from the Download Software 
area of the ADC Member Site at: 
bttp://connect, apple, com/ 

• WebObjects 5 Trial 

Trial version of WebObjects 5, expires 9/30/2001. NOTE: 
WebObjects 5 Trial is the same as what is available under Mac OS 
X Developer Tools link. Please See WebObjects 5 Key doaiment 
for licensing information, 

• Mac OS X Java 3.1 Developer Preview 2 and Java 3.1 
Documentation 

Mac OS XJava is an implementation of Java 2 Standard Edition 
1.3.1, including the client version of HotSpot 13.1 Tirtual 
Machine, which UP2 uses exclusively. For improved applet behav¬ 
ior with this release of Java, use Software Update to install 
Miemsoft Internet Explorer 5.T1 Preview, 

• CarbonLib l,4a6 SDK 

The latest pre-release version of (’.arbonLib 1,4 SDK for Mac OS is 
now available to all ADC Members. This SDK provides all the files 
needed to begin Carbon development. CarbonLib 1.4 supports 
Mac OS 8.6 and greater, 

• Apple System Profiler 2.6.Ia6 

Contains AppleScript fixes, launch speed improvements, OS X 
report sync, search option window fixes. 

• Mac OS X Developer Tools 10.0.1 

Downloadable version of the May 2001 Developer Tools CD 
distributed at UWDC to attendees. Contains the Mac OS X 
Developer Tools 10.0.1, and a trial version of WebObjects 5 
which expires 9/30/2001. NOTE: The Carbon SDK is not 
included. 

Developer Documentation 

The following new and updated documentation is available to 
help with successful Mac OS X application and peripheral 
development at: 

bttp://developerMpple, com/techpubs/ 


Carbon Specification 

Aqua Human Tnter&ce Guidelines 

Technical Notes 

TN1044 - Fundamentals of Open Firmware, Park 111: 
Understanding PCI Expansion ROM Choices for Mac OS 
TN2016 ~ iUines Tisual Plugdns 

TN2022 - The Death of typeFSSpec: moving along to typeFileURL 
Technical Q&As 

QA1053 - Using Pascal string$ in Project Builder 

QA1043 - Using SeiMovieGWorld to draw to the window back 

buffer 

QA1044 - Exporting TIFF files in little endian format 
QA1040 - 128Mb SDRAM Ics limitation on original "Bronze 
Keyboard'' POwerbook G3 

JAVA28 - Creating JNl Libraries with Project Builder 

QA1039 ^ Fixing NSDocumentController to understand HFS file 

ri^pes 

QAi038 - HID Manager Event Data Underruns 
Sample Code 

SC - Graphics 3D: OpenGL Image 

SC - Cocoa: SimpieCocoaMovie 

SC - Graphics 2D: CTMDemo 

SC-Graphics 2D: CTMClip 

SC - Sound: CASoundLab2 

SC “ Graphics 3D: Carbon SetupGL 

SC - Graphics 2D: BlitVBL 

SC — Graphics 2D: BlitNoVBL 

SC - Sound: AIFF writer sdev 

SC - Graphics 3D: aglString 

SC — Graphics 2D: CGGamma 

SC - Human Interface Toolbox: Tiler 

SC - Human Interface Toolbox: PackageTool 

SC-Java: JNISample 

SC^ - Cocoa: bMoviePalette 

SC - Devices and Hardware: HID Manager: HID Utilities Source 
SC “ Devices and Hardware: HID Manager: HID Config Save 
SC - Devices and Hardware: HID Manager: HID Explorer 
SC — Devices and Hardware: HID Manager: HID Manager Basics 
SC — Graphics 3D: NSGL Teapot 
SC - Networking: NSLMiniBrowser 
SC - Java: JavaSpellingFtamework 
SC - Java: JavaSpeechFramework 










updates from the Apple Developer Connection 

Avgust 2001 


Making It Aqua 

Continued from page 47 


Final Note: Looks Are Everything—Almost 

Remernber, users often judge the quality of a product by its appearance 
(or user intetfece.) So, if the visual presentation of your produa is not 
Aqua compliant, they’ll assume the overall functionality of the product 
is the same. Don’t leave your UI work until the last minute. Build prod¬ 
ucts that feel complete and have the Aqua look-and-feel. Pay attention 
to the details and you’ll reap the rewards, Good luck, 


Did You Know? 

Biueprints For Aqua Human Interfaces 

A major goal for graphical human interfaces, aside from 
being intuitively usable and aesthetically pleasing, fs 
consistency. Applications and system soft\vare should 
play by the same interface rules, whether those rules determine 
the placement of buttons on a dialog or the behavior of win^ 
dows. If one or more applications were to do things differently, 
the resutting disharmony and confusion would degrade the 
user*s experience. 

To help developers design their applications' human inter¬ 
faces to the same, well-considered standards, Apple Technical 
Publications provides /ns/de Mac OS X: Aqua. Human interface 
Guidelines. As a collection of blueprints for designing Aqua 
interfaces, this book is an indispensable resource. These guide¬ 
lines will help you design modern, elegant applications that 
meet users* expectations of Macintosh software: intuitive, 
attractive, easy to learn, and enjoyable to use. 

Inside Mac OS X: Aqua Human Interface Guideiinss starts 
by explaining the principles that influence the design of Aqua 
human interfaces, including user control, direct manipulation, 
and forgiveness. Then, using specific examples and annotated 
figures, the book describes in detail how each part of the Aqua 
interface should look and behave. Individual chapters cover 
menus, windows, dialogs, controls and general layout, user 
input, fonts, icons, drag and drop, help, and terminology. 

You can obtain a bound, print-on-demand copy of 
inside Mac OS X: Aqua Human Interface Guidelines from 
Fatbrain.com at hnp://www1.fatbraHcom/documenta^on/appie. 
You can also get PDF versions of the book from the 
Developer Essentials page of the installed and on-line 
{http://deveIoper.appte.com/techpubs/macosx/SystemOverview 
/devessentiafs.htmi) developer documentation. 


Upcoming Seminars 
and Events 

For more information on Apple developer events please 
visit the developer Events page at: 
http://developer. apple, com/events/ 

Training and Seminars 

R/com Offers Mac OS X Developer Training Online 

R/com, also knoAvn as MediaSchool 
<www.mediaschool.com>, has partnered with Apple 
Developer Connection to create online training for Mac OS X 
developers. The first courses to be released in July Include 
‘Application Development for Mac OS X,"* “Carbon 
Development for Mac OS X," and “Cocoa: The Object- 
Oriented Application Solution.” All classes have been 
reviewed by Apple engineers for technical accuracy. Check 
out their site to take a free virtual seminar, to learn more 
about current and upcoming courses, and to find out about 
the significant discounts offered to Premier, Select, and 
Student members of the Apple Developer Connection. 
bt^://www. mediaschool. comfodc/ 

Apple (Services 5‘day Cocoa Training 
For application developers who want to learn how to develop 
Mac OS X applications using Cocoa, Apple iServices offers a 
five-day comprehensive, hands-on Cocoa training course. This 
course uses real-world examples and is perfect for developers 
who have a general understanding of Object-oriented con¬ 
cepts and practical experience with the C programming lan¬ 
guage or a C-derived language (Object-C, Java, or CH- +). The 
course costs US $2,495. 

hnp://wum^.ap{de.com/iServicesdecbnk€dtniimng/cocoad€ubtml 

Developer-Related Conferences 

FileMaker Developer Conference 2001 

August 12-August 15, Orlando, FL 

More than 50 sessions and a product showcase. Wrious 

FileMaker training classes offered concurrendy. 

hup; //WWW.filemakeKcom/devcon/ 

http://umuiDevcon Training, com/ 

Apple Expo 2001 
September 26-30 
Porte dc Versaille, Hall 4 
Paris, France 

bttp;llwww^ apple-expo, com/ 










QUICKTIME 

TOOLKIT 


by Tim Monroe 


The Skin Game 


Working with QuickTime Skins 


Introduction 

QuickTime 5 intrcjduced support for displaying movies 
inside of arbitrarily shaped windows. These windows are 
called skinned movie itnndows, and the custom shape of one 
of those windows is called its skin. Up to now, our sample 
applications have always displayed QuickTime movies inside 
a standard document window, which occupies a rectangular 
area on the screen. Even QuickTime Player, which uses a 
snazzy brushed-metal window frame with rounded edges, 
always shows a movie inside a rectangular pane inside the 
frame. Skins give us a way to break out of this rectangular 
mold. For instance, Figure 1 shows a QuickTime movie with 
a skin thafs shaped like the QuickTime logo. 



Figure 1: A QuickTime tnovie mtb a skin 


This movie contains two video tracks, one for the grainy, 
grayscale video showing in the center of the logo, and one 


for the logo image itself. (The second video track contains a 
single sample that extends For the entire duration of the first 
track.) The user can start and stop the movie by pressing the 
spacebar or by clicking in the visible portion of the grayscale 
video. And the user can move the window around on the 
screen by clicking anywhere on the blue logo and dragging. 

Figure 2 shows another possibility. Here is our penguin 
sprite movie once again, but this time as a skinned movie. It's 
.still got a tween track that changes the sprite’s graphics mode 
from total traasparency to total opacity. But now Tve set the 
looping mode to palindrome looping so that the penguin 
fades in and out as the movie plays. 



Figure 2: Anoiber QuickTime movie mtb a skin 


Figure 3 shows yet another skinned movie window. 
Most of what you see here, including all the buttons and 
draggable handles, is provided by a Flash track. The grayscale 
image is once again a frame of a video track, which we can 
start, stop, pause, and play in slow motion using the tools 
palette on the right side of the movie window. 


Tim Monroe is intrigued to discover that his lizards often eat ihek own skin after they molt. You can explain this to him at moriroe@apple.com. 
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WWW. apple, com/quicktimelive 







Figure JL' Yet another QuickTime movie with a skin 

In this article, we*re gcnng to learn how to create 
skinned movies. More importantly, weVe going to learn how 
to open a skinned movie file and display the movie to the 
user in a window of the appropriate shape. That is to say, 
weTe going to learn how to make our applications skin 
savvy. Currently there are very few applications that can 
open skinned movies. The only widely-available application 
that can do this, to my knowledge, is QuickTime Player. 

Our sample applic'ation in this article, which can both create 
skinned movies and play them back, is called QTSkins. The Tes1 
menu of QTSkins Ls shown in Figure 4; as you am see, it has only 
one menu item, which aQow^s us to add a skin track to a movie. 


Test 


Rdd Skin Track... 9g1 ] 

Figure 4: Tlye Test menu of QTSkim 

Skins 

Perhaps the best way to think of QuickTime skins is like this: a 
skinned movie is just a QuickTime movie wiili a custom window 
shape. A skin provides a way of selecting some portitm of an 
existing movie and having that portion be all that's displayed to the 
user when tiie movie is opened. Skinned movies don’t have title Ixirs 
or window frames, and they don’t display a controller bar. As a 
result, il’ we want die user to be able to interact with the movie, well 
need to supjily our own controls. We can use wired sprite tracks or 
Flash tracks for this, or peiiiaps even wired text tracks (which we 
encountered in the previous article). 

The data tliat defines the custom window shape is 
contained in the skinned movie file itself. Tliis fact has some 
very important consequences. For one thing, it means dial we 
can select on a per-movie basis whether a movie is displayed in 
a normai document window or in a custom-shaped skinned 
window. WeTe not modifying the genera! appearance of the 
playback application (which is perhaps the typical use of the 


term 'skins'). Rather, we’re modifying the specific appearance of 
what’s being played back. In a nutshell, weTe changing the 
movie, not the movie player. Previously, the movie data 
represented some ctmtenl that plays back inside a document 
window or pane, usually under the supervision of a movie 
controller and controller bar. Now the movie data can represent 
the content and the window and the controller. For the first 
time, really, the movie author has complete control over the 
user’s playback experience. 

So what kind of data do we use to construct a skinned 
movie? The first thing we need is some way of specifying 
which portion of the movie rectangle we want to appear as 
the content region of the ,skinned movie window. The 
content region of a window is the portion of the window in 
which an application displays the contents of a document; in 
our case, it’s where the movie data and any movie controls 
are displayed. We specify the skinned movie's content region 
by providing a l-bit (that is, black and white) mask that’s the 
same size as the movie rectangle. If a pixel in the mask is 
black, then the corresponding pixel in the movie rectangle is 
displayed; otherwise, the corresponding pixel is not 
displayed. Let's call this mask the content region mask 
Figure 5 shows the content region mask for the skinned 
movie shown in Figure 1. 



Figure S:A content r^ion fnask 


We also need some way to move the skinned movie 
window around on the screen. Typically, of course, we move 
a window by grabbing its title bar or window frame and then 
dragging. Because skinned movie windows don’t have title bars 
or frames, however, we need to explicitly indicate the portion 
of tlie skinned movie window that the user can grab and drag. 
We do this by specifying a second mask, the drag region mask. 
(This is also a 1-bit mask.) A user can click anywhere in this 
region and drag the window around. Figure 6 shows the drag 
region mask for the skinned movie shown in Figure 1. 
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No Mac is complete without Timbuktu Pro, 
the premier remote control and file transfer 
software for Mac OS for over ten years. 

No network is complete without the smart 
systems management of netOctopus. 
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bringing the power and simplicity of Netopia 
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Figure 6: A drag region mask 


You'll notice that the drag region mask is entirely contained 
within the content region mask, so that the user can grab only 
in some visible portion of the movie \vindow. In addition, the 
drag region mask should exclude any areas of the movie 
rectangle that you want to be interactive. It won't do any good, 
for instance, to have a skinned movie's drag region overlap any 
wired sprites, since a click in that area will be interpreted as the 
beginning of a drag operation. 

So we need three ingredients to create a skinned movie. We 
need the movie data itself. We need a content region mask, to 
indicate the portion of the movie rectangle that is displayed to 
the user. And we need a drag region mask to indicate tlie 
portion of the movie rectangle that can be grabbed. 

Creating Skinned Movies 

The typical way to create a skinned movie is to add a skin 
track to an existing movie. The skin tmck contains data that 
specihes die content region and tlie drag region of the movie 
window. In this section, we'll investigate two different ways to add 
a skin track to a movie. First, tliough, weT take a brief moment to 
learn about media charaaeristics. Tills will help us see that skin 
data c'^an in fact be contained in tirher kinds of tracks as well. 

Searching Media Characteristics 

Let's begin by considering a utility function well call several 
times in our application, QTSkin_lsSkinnedMovie (defined in 
Listing 1). Tills function returns a Boolean value that indicates 
whether the specified movie contains skin data. 

Listing 1: [>etermining whether a movie is a skinned 
m ovie ___ 

QTSkinJsSkitinedMovie 

Boolean QTSkin_IsSkinnedMovie (Movie thoMovie) 

I 

r etu r n C GetHo vi e I nd TrackTyp e ( th. eMo vi e, 1, 

FOUR_CHAR_CODE (* skin ‘), mo vieTrnckChar act eristic) 

!= HULL): 

! 

We’ve worked with GetMovielndTrackType a handful of draes 
previously, but only using die movieTrackMediaType flag as the last 
parameter, to search for a track of a ^ven index that has a specific 
type. Here, youll notice, we use the movieTrackChatacteristic flag 
instead, which tells GetMovielndTrackType to search for a track of 
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a given index that has a specific media chaiacteristic. A media 
characteristic is a feature that can be shared by or more track 
types, such as the ability to draw data. Originally, in QuickTime 
version 2.0, there were two supported media chamcteristic's, 
indicating whether the track has video or audio data in it: 

enuia [ 

VisualMediaCharacteristic = F0UR_CHAR_C0DB{'eyes'), 

AudioMedlaCharacteristic * F0UR_CHAR,_C0DEC‘ears') 

1; 

Any track tliat displays visible data to the user has the 
VisuaiMediaCharacteristic media characteristic; some examples are 
video tracks, sprite tracks, text tracks, MPEG tracks, and timecode 
tracks. Similarly, any track that plays audible data to the user has 
the AudioMediaCharacteristic media characteristic; some examples 
are miind tracks and music tracks. QuickTime has subsequently 
added a few other .searchable media characteristics, mcluding 
kCharacteristicProvidesActions for tracks tliat contain wired actions. 

In listing 1, we’re icx>king to see whetlier any track in the 
movie contains skin data, (Tliere Is as yet nti pubiidy-defined 
constant for the skin media characteristic, so we’ve hard-axled the 
value FOUR_CHAR_CODE(‘skin’).) Skin tracks certainly contain skin 
data, so they have this chatacieristic. But otJier kinds of tracks may 
very well contain skin data, and so lliey too would have tills 
characteristic. (If we are inlerestetl in knowing whether a specific 
track has a given characteristic, we can call the 
MediaHasCharacteristic function.) By searching for the skin media 
characteristic iastead of tlie skin media type, we allow otir 
applications to work wiili any movie tracks tliat contain skin data. 
Right now, to lie sure, there are no track types with that 
characteristic aside fmm skin tracks; but we are equipped to deal 
witli them wlien they come along. 

Using the Quicklime XML Importer 

By far the easiest way to create a movie with a skin track Ls to 
use a QuickTime XML importer, intnxluced in QuickTime 5. XMl 
(for Extensible Markup Lungua}>e) is a textual description of a 
d(x:ument that contaias structumd information. It’s similar in flavor 
to HTML, but differs significantly in Uiai XML dtjes not have a 
predefined set of markup tags. Rather, XML Ls more of a 
metalanguage for describing structuied information. A QuickTime 
XMl importer is a movie importer that knows how to parse certain 
kinds of XMl. files. QuickTime provides an importer that knows how 
to parse XML files that contain tags descTibing a skinned movie. 
Listing 2 shows the file used to construtt the skinned movie show^n 
in Figure 1. As you can see, this XML file specifies three (Xher files, 
wliich contain the original movie data, a mask for the aintent tegion 
of the window, and a mask for the drag region of the window. 

Listing 2; An XML flic that specifi es a s kinne d movi e 

SkirmedQfLogo.xmJ 

<?xiiil ver:sion=‘'l 

<?qtiitktime type="appllcatlonyx-qtskin"7 > 

<skin> 

(movie erc=''QTLcigo.incsv"/> 

< content region s t content ma sk. pc t ” / > 

<dragregion src="dragiiiask.pct"/> 

</skin> 


If we Open this file using QuickTime Player or any other 
skifi-sawy application, well see the skinned movie shown in 
Figure 1. The application probably calls New Movie From File or 
NewMovieFromDataRef to open the XML file. QuickTime will see 
that the file doesn't contain a movie atom and then go looking 
for a suitable movie importer. (See “In and OuG Ln MacTechy 
May 2(X)0, for a more in-deptli discussion of how this works.) In 
the present case, QuickTime will invoke the XML importer to 
import the movie data and return a movie to tlie calling 
application. Note that some importers, including the QuickTime 
XML importer, seem to ignore the newMovie Active flag passed to 
NewMovieFromFile. So well add the following line of code to the 
QTFrame_OpBnMt>vielnWindow function, after we call 
NewMovieFromFile; 

SetMoviaActive[myHovie. true) : 

We can create a self-contained skinned movie file by calling 
FtattenMovieData on the open skinned movie. Our sample 
applications make this call when the user selects the “Save As. 
menu item. The self-contained movie file is easier to move 
around and to transport from machine to machine. Ifs also 
preferable for wel>based movie delivery. 

Creating Skin Tracks Programmatically 

Using the XML importer is fine and dandy, but we'd also 
like to be able to create skinned movies directly, using the 
QuickTime APIs, Once again, we’ll do tills l>y adding a skin track 
to an existing movie. We've created many kinds of tracks in 
QuickTime movies, so we’ve got the drill down. You 11 recall that 
it goes basically like this: 

• Create a new' track and media (NewMovieTrack and 
NewTmekMedia), 

• Create a new sample descriprion (NawHandle). 

• Start a media-editing session (Beg in Media Ed its). 

• Add media data to the new media (AddMediaSample). 

• End the media-ediiing session (EndMediaEdits). 

• Insert the new medki data into the track (InsertMedialntoTrack). 

It rums out, how^ever, that we need to use a slightly different 
metliod for consiaicting a .skin track. When we build (for 
instance) a video tnjck or a sprite tmek, we need to know the 
exact structure of the media sample data, and w^e need to fill out 
a sample description that describes that data (its size, its 
compression type, and so forth). Moreover, when w^e call 
AddMediaSample, we need to specify the duration of the media 
sample. But with skin media data, die notion of duration doesn't 
really apply. After all, we're just specifying a couple a masks for 
a window shape, not any time-based data. 

To .simplify our handling of media data tliat isn't time based, 
QuickTime 5 introduced public media information, which can 
be any data associated with a media that does not need to be 
pegged to a specific time in a track. Currently, to my knowledge, 
only the skin media handler supports public media information, 
to maintain the content and drag region masks. 

QuickTime 5 includes two new functions for working with 
public media information, MediaSetPublicinfo and MediaGetPublicInfo. 
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MediaSetPublicInfo is declared essentially like this: 

ComponentResult KediaSetPublicInfo[HediaHandler mh, 

OSType infoSelector, void *infaDataPtr. Size 
dataSlze): 

The mh parameter specifies the media handler we’re giving the 
informaticm to; in the present case^ it's the skin media handler The 
infoSelector parameter specifies the kind of public information 
we’re setting. The skin media handler currently understands Iwo 
seleaors, ^skcr’ (for the content region mask) and 'skdr' (for the 
drag region mask). The parameters infoDataPtr and dataSize specify 
the memory location and size of the public media infomiation 
data. With the skin media handler, however, dataSize should be 0 
and infbDataRr should be a picture handle (of type PicHandle). For 
instance, here's how we'll set the content region mask: 

myErr = MediaSetPublicInfo(myHEndler. F0UR_CHAR_C0DE["skcr’), 
(void *)myContentPic* 0); 


// haw the user select an image file 
niyFiltertJPF = Q!TFraine_GetFilePllterUPP ( 

(ProcPt r)QTSkin_FlieFiIte rFunctlon): 

myErr ” qTFrame_GetOneFllGWithPrevlGw(iiiyNumTypes. 

(QTFrameTypeListPtr) imyTypeLlst, &inyPictSpec, 
myFilterUPP}: 
if (myErr [“ noErr) 
goto ball: 

// get a graphics importer for the image file 
myErr = GetGraphicslmportGrForFile(&niyPictSpec, 
firinyImporter); 
if (myErr (= noErr) 
goto ball: 

// convert the image into a PicHandle 

myErr = GrapbicsIniportGetAsPicture(mylmporter. fimiyPicture) ; 
bail; 

if CmyFiltGrUPP !“ NULL) 

DisposGNavObJectFilterUPP{myFllterUPF): 

if (myImporter !“ NULL) 

CloseCompotiGiit (mylmporter): 


Our work really boils down to this: have the user select two 
pictures, one for die content region mask and another for the 
drag region mask; then create a new track and media (of type 
^skin’), call MediaSetPublicInfo for each of the pictures selected by 
the user, and finish up by calling InsertMediaIntoTrack. Once 
weVe got the two picture handles, die 6-step sequence listed 
above reduces to this: 

• Create a new track and media (NewMovieTtack and 
NewTrackMedia). 

• Add media data to the new media (MediaSetPublicInfo). 

• Insert the new media data into the track (InsertMediaIntoTrack). 


Lefs consider, then, how to get the two picture handles. 
Ideally, we’d like to allow the user to work with any kind of 
image file that QuickTime can open (just like the XML importer 
does). MediaSetPublicInfo expects the data we pass it to be a 
PicHandle, so we need some way to convert the image data in a 
file selected by the user into a PicHandle. Happily, there is a 
graphics importer function, GraphicsImportGetAsPicture, that 
does precisely this. Listing 3 defines the 
QTSkin_GetPicHandleFromFile function, which we use (in Listing 
4) to prompt the user for the tw'o images we need. (For more 
information about graphics importers, see "Quick on the Draw” 
in Maclech, April 2000. ) 


Listing 3: Getting a picture handle from an image file 

QTSkm_GetPicHaadleFroniFi]e 
PicHandle QTSkin_GetFicHQndleFroraFile (void) 
f 


OSTypG 

abort 

FSSpec 

QTFrameFileFiltGrtTPP 
G r aphi c a Imp o rt Conipo nent 
PicHandle 
OSErr 


myTypeLlst = 

kQTFi1eTy p eQuic kTimeIma ; 
myNmnTypea = 1 : 
myPictSpec: 
myFilterUPP = NULL: 
myimpotter “ NULL: 
myPlcture NULL: 
myErr = noErr: 


#if TARGET_OS_MAC 
myNumTypes = 0: 
#endif 


return(myPicture): 

I 


We are finaUy ready to put this all together. When the user 
selects the “Add Skin Track...” menu item, we execute the 
QTSkin_AddSkinTrack function defined in Listing 4. 


Listing 4: Adding a skin track to a movie __ 

QTSkb.AddSkinTrack 

OSErr QTEkin_AddSkinTrack (Movie theMovie) 


Track 

Media 

Rect 

MediaHandler 

PicHandlG 

PicHandle 

OSErr 


myTrack = NULL: //the movie track 

myMedla = NULL: //the movie track's media 

niyRect: 

myHandler = NULL: 
my ContentPic = NULL; 
inyDragPic - NULL: 
myErr “ paramErr: 


if (tbeMovie = NULL) 
goto bail: 


// elicit the two piaures we need from the user 
myContentPic = QTSkin_GetPicHandleFroiiLFile[); 
if (myContentFic = NULL) 
goto bail: 

myDragPlc “ qTSkin_GetPiGHandleFrcniiFile () ; 

If CmyDragPic = NULL) 
goto bail: 


// gel the movie's dimensions 
GetMovieBox(theMovieH SmyRect): 

MacOffsetRectCSimyKect. -myRect .left. -myKect. tup): 

// create the s^kin track and media 
myTrack = NevHovieTrack(theMovie, 

FixRatio(myRect.right, 1), 
FixRatio{myRect,bottom, 1), kNoVolume): 
if {myTrack ^ NULL) 
goto bail; 

inyMedia = NewTrackMedia(myTrack, F0UR_CHAR_C0DE{'skin*), 
GetMovieTlmeScale(thcHoviG). NULL. 0); 
if (jnyMedia = NULL) 
goto bail: 

myHandlGr = GetMedlaHandler{myMedia): 
if (myHandler ^ NULL) 
goto bail; 

// add the skin content piemte as public media information 
myErr = MediaSetPublicInfo (myHandler, 
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FOtIll_CHAlL_CODE (* skcr *) * 

(void “3myContentPic, 0]: 
if (myErr I” noErr) 
goto ball; 

// add the skin drag piaurc as puMic media information 
myErr = MediaSetPublicInfolinyHandler. 

F0tJR_CHAE_C0DE (’ skd r ^). 

(void *}(iiyD.ragPic, 0); 
if (inyErr 1= ooErr) 
goto bail; 

// add die media to tbe track 

rayErr ^ InsertMediaIntoTrack(inyTrack, 0* 0, 

GetMedlaDurationCinyMedia), fixodl] * 


bail: 

If (myContentPic != NULL) 
KillFicture(myContentPic): 

if (myDragPic E= NULL) 
KillPicture[myDragPic): 

return (ntyErr): 



New: PrimeBase 4.0 ! 



Using PrimeBase, you are able to produce 
Internet and Intranet Applications faster and with 
the best performance ever. 


As you can see, using MediaSetPublicInfo greatly simplifies 
creating a skin track. We don't liave to create a sample description, 
and we don't need to call BeginMediaEdits or AddMedlaSampie or 
EndMediaEdits. The skin media liandler takes care of all the details 
of storing the cxinteni and drag region masks Ln the skin media. 

Skinned Movie Piayback 

<So now we know how to build a skinned movie, using either 
the QuickTime XML importer or our own application code. As 
mentioned earliei; we also want our application to be able to open 
and play back skinned movies. Thus turns out to be significantly 
more implicated, however, since we need to be able to assign a 
custom window shape to a movie window and window shapes are 
handled by the application, not by QuickTime. So, we're going to 
have to get acquainted with some of the Jow-level window¬ 
handling t'apabilides of our host operating systems if we want to 
be able to open and manipulate skinned movies. 

On Macintash operating systems, we assign a custom shape to 
a movie window by writing a custom mridow deJinUion procedure. 
Under Carbon, the code for a custom window definition prexedure 
is cx)ntained in the application itself, not in a code resource of type 
WDEF’ (as in tlie pre-Carbon Mac world). Onc'e weVe defined our 
custom procedure, we can call the CreateCustomWindow function to 
create a skinned movie window. Wlienever the Window Manager 
needs to draw our custom window or handle clicks on it, it adls our 
custom window definition procedure. 

On Windows operating systems, it's even easier to assign a 
custom shape to a window: we t'an cal! the SetWindowflgn 
function when opening the movie window to assign an arbitrary 
region as the window shape. We'll also add a little code to our 
basic movie window procedure QTFrame_MovieWndProc to 
handle skinned window dragging. 

Before we can do any of thus, however, we need to get ahold of 
the skin data that determines the window's appearance and drag 
behavior. That is, we need to read the content and drag region masks 
out of the skinned movie file. As you might guess, we'll use 
GetMediaPubiicInfo to get the picture data stored in the skin track. 
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Then we’ll need to convert thiii pictuie into a region, which woU that graphics world, listing 5 shows our definition of 
pass to the operating system window handlers. QTSk!n_ConvertPk:tureToRegion. 


Setting Up the Application Data 

For each skinned movie file we open^ we need to maintain 
some application-specific data. Basically, we need a place to 
keep track of the various regions describing the geometry of the 
skinned movie window^ In the file ComApplication.h, well 
declare the ApplicationDataRecord data structure like this: 


typedef struct ApplicationDataRecord [ 

RanHsndle f Content Region: // content region of window 

RgnHandle fDragReglonj 

RgnHandle fStructRegion: 

#if TARGET_OS_HIN32 
HRGN fWinHRGN: 

#endlf 

I ApplicationDataRecord* ‘ApplicationDataPtr* 

*'ApplicationDataHdl 


// drag tegiofi of window 
// stmemre region of window 

// window region 


The fContentRegion and fDragRegion fields hold handles to the 
content region and the drag region of the window, which we 
retrieve from the skin track as weTe opening a skinned movie. 
The fStructRegion field holds tlie structure region of the skinned 
window. A window's structure region Ls the entire screen area 
occTjpied by tlie window, including die window's content regitm 
and its window frame. For skinned movies, the struaure region 
is usually identical to its content region. The fWtnHRGN field 
holds the window content region as an object of type HRGN, This 
is the object we’ll to pass to SetWindowRgn when we set the 
window's shape on Windows. 

Recall that the data stored in a .skin track is of type PIcHandle, 
We c’an retrieve that dam by calling GetMediaPublicInfo, passing it 
a selector for the type of information we want. For instance, to 
retrieve the content region mask from a skin track, we can 
execute diis code: 

tnyPicture “ (PicHaudlelMeTirHandle(0) ; 
if (myPlcture = NULL) 
goto bail; 

myErr - MediaGetPubllcIjifq (myHaTidlcr * F0UR_CHAR_C0DE{‘ eker *) * 
myPicture, NULL)i 

If GetMediaPublicInfo completes successfully, myPicture will 
contain a handle to the picture data. We then need to convert 
this picture data into a region, since that’s the kind of data well 
need to have available in our custom window definition 
procedure. We make this conversion by calling the application 
funaion QTSkin_ConvertPictureToRegion: 


listing Ss C onfvertin g a pictnre totp a rcgioii_ 

QTSkin^CoiiviertpicmreToSegion 

OSErr QTSkin^ConvertPlctureToRegion [PlcHandle thePicture* 
RgnHandle "'theRegionPtr) 


Rect 

GWorldPtr 

PixMapHandle 

CGrafPtr 

GDHandle 

RgnHandle 

OSErr 


myRect; 

myGWorld - NULL; 
myPiKMap = NULL: 
mySavedPort = NULL; 
mySavedDevice “ NULL; 
myRegion = NULL; 
inyErr ^ noErr; 


if ([thePicture ™ NULL) [ | (theRegionPtt — HULL)) 
return EparainErr); 


a gti ihc cuTTcai graphics port and device 
GetGWorld(&iiiySavedPnrt, ^mySavedDevlce); 

// get the boiiiKihig Ixix of the picture 
tnyRect = (*‘thePicture) .picFrante: 

EiyRect.bottom - EndianS16_ltoN(myRect.bottoni): 
myRect.right = EndisnSl&JBtoNCmyRect.right): 

H create a new GWorid and draw the picture into it 

myErr = QTNevGWorldi&myGWorld, klHonochromePixelFormat, 

iirayRect, NULL, NULL, klCMTempTbenAppMemory); 
if CmyGWorld NULL) 
goto bail: 

SetGWorldEmyGWorld. NULL): 

myPixMap ^ GetGWorldPixHapimyGWcirld); 
if CmyPixHap “ NULL) 
goto bail; 

LockPixelsEmyPixMap): 

HLockE(Handle)myPixHap]; 

EraseRectE&myRact); 

DrawPicture(thePicture. imyRect); 

// create a new legion and convert die pixmap Into a region 
myRegion = NewRgn(); 
myErr = MemErrorO; 

If ErayErr noErr) 
goto ball: 

myErr BltMapToRegionCmyRegloti. (BitMap ♦) •myPixMap) ; 


bail; 

if finyErr noErr) [ 
if (myRegion != HULL) f 
DlsposeRgn(myRegion): 
myRegion ^ NULL: 

I 

) 


if fmyGWorld !" NULL) 
DiaposeGWorld(myGWorldJ; 

// restore the original graphics port and device 
SetGWorld (mySavedPort. mySavedDevice): 

'theRegionPtr = myRegion: 


myErr “ QTSkin^ConvertPictureTaRegion(myPicture, 
&E**myAppData).fContentRegion); 


return(myErr); 


QTSkin_C)onvertPictureToRegion creates a region that cxjntains 
every nc;)n-white pixel in the specified picture. The key step is u.sing 
QuickDraw’s BitmapToRegion function to conveit a bitmap or a pixel 
map into a region. So we need to create a pixel map from our 
picture data. But this is very easy; we simply create a new oflfecreen 
graphics world and draw the picture data into it W can then use 
^e GetGWorldPixMap function to gel the pixel map associated with 


For our Windows applications, we need to take one further 
step and conveit the Macintosh region (of type RgnHandle) into 
a Windows region (of type HRGN). The QuickTime Media Layer 
provides a function that will do this for us; 

C**myAppData}.fWinHRGN ^ MacRegionToNativeRegion 
(E" ’myAppOata) . fConteiitRegion) : 
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All of this stan-Lip code will go into the function 
QTSkln_lnitWindowData, which is called by 
QTApp_SetupWindowOb]ect to perform any application'Specific 
initialization of the movie window and its associated data. 
QTApp_SetupWindowObject contains this code to handle 
skinned movies: 

if (QTSkin_IsEkinnedMovie(myMovie}) [ 

// hide the conLroller har 
MCSetViGible(tnyHC. false): 

// detach the coatroUer 

MCSetControllerAttached (myHG, false) ; 

// initia]i?.e the window data for a skins movie 
('nheWindovObJect) .fAppData “ 

(Handle)QTSkin_InltWindowData(theWindowObject): 


When QTApp_SetupWindowObject is called, the skinned 
movie window has already been created but it has not yet been 
displayed to the user. On Windows, we used our standard 
function QTFrame_C reate Movie Window to create the movie 
window. So at tliis point, on Windows, we can already call 
SetWindowRgn to set tlie shape of the skinned movie window: 

if ((**TnyAppData) .fWlnHRGN r= NULL] I 
RECT myRect; 

int myReBult: 


GetRgnBox ((* *niyAppData). fWinHRGN. StmyRect): 


I 


OffsetRgnC ^myAppData) h fVlnHRGN. 

-myRect.left + GetSyst6mMetrlcs(SH_GSRRAME], 
'ByRect.tQp + GetSysteuiMetrlcs (SH_CyGAPTION) + 
GetSyatemMetrica(SK_CYFRAME}): 
myResult = SetWindowRgn({* * theWindowObj act).fWindow, 
{• * my Ap pUata). f W1 tvHRGN, true) : 


SetWindowRgn sets the visible region of a window; it expects the 
origin of the window region we pass it to be relative to the 
upper-left corner of the window, not relative to the client area 
of the window. So we need to offset the stored window region 
(**myAppData}.fWinHRGN horizantally by the width of the 
window frame and vertically by the lieight of tiie window' frame 
and the height of the title liar (or caption). Figure 7 shows the 
penguin window with these offsets. 



Figure 7: 7he dietU region offsets 


As far as Windows Ls concerned, the window frame and 


window controls still exist — they are fust not visible on the screen. 
The window is a fuE-fledged MDI child window, fast like any of our 
other (non-skirmed J movie windows. The only dilfefence is that the 
skinned movie window has a special visible region. 

Listing 6 shows the full version of our skinned movie 
window initialization code. 


Listing 6; Initializing the application data for a skinned 


mov ie 


QTiiklnJnitWindowData 

ApplicatiOQDa.taHdl QTSkln_InltWindowData 

(WindowObject tbeWindowObJect) 


AppiicationDataHdl 
Tra r k 

MediaHandler 

PicBandle 

MatrixRecord 

OSErr 


tnyAppData " NULL; 
myTrack - NULL: 
my Handler == NULL: 
myPlcture ” NULL: 
myMatrijt: 
myErr ^ noErr: 


// if we already have some wtadow data, dump it 
myAppData ^ 

(ApplicationDataHdl)QTFranie„GetAppDataFroiiiWindowObject 
(theWindowObject): 
if (myAppData t= NULL) 

QTSkin_DumpWindowData(tbeWlndowObject); //see Listing 14 


myAppData = 

(ApplicationDataEdDNewHandleClear 

(siaeof(ApplicationDataRecord)): 
if (myAppData !" NULL) [ 

myTrack ^ GetMovielndTrackType 

({•*theWindowObject).fHovie. 1. F0UILCHAR_C0DE(Vskin^) . 
movieTrackCharaateristic); 
if {myTrack 1= NULL) [ 

myHandler ^ GetMediaHandler [GetTrackMadia(niyTrack)) : 
if (rayHandler 1“ NULL) [ 


// get the airrcnt movie ttiatrix 

GetMovieHatrlx{(* * tbeWindovOb j ect).fMovie, 

SLiuyNatrix.): 

myPicture ^ (PicHandle)NeitfHandle(O): 
if (inyPlcture ” NULL) 
goto bail: 


// get the eonteni region picture 

myErr ^ HediaGetPuhIicInfo{myHandler. 

FOUR_CHAR_GaDE(‘skcr*). myPicture. NULL): 
if [myErr 1= noErr) 
goto ball; 

// convert ft to a. region 

myErr = QTSkiu_ConvartPictureToRGglon (myPicture * 
£i(**myAppData) .fContentRegion): 
if (liiyErr noErr) 
goto bail: 

// scale that region $o the window scales with the movie 
myErr ” Transf orniRgn (SonyHatrix, 

('^myAppData).fContantRaglon): 
if (myErr ]= noErr) 
goto bail: 

#if TARGET_OS_WIN32 

[•^myAppData) .fWinHRGN ^ HacRegionToNativeRegicin( 
(''myAppData).fContentRegion): 
if (("myAppData) .fWinHRGN !- NULL) t 
RECT myRect: 

int myResultt ^ 

GetRgnBox{("myAppData). fWinHRGN* ^myRect): 

// the ajottlinites of a window region are relatf^'e to the upperieft corner 
// of tile window (not to the client area of the window') 

OffsetRgn{ ("myAppData) .fWinHRGN, 

-myRect.left + GetSystemMetrics(SM„CXFRAME). 
“myRect,top + GetSystemMetrlcs(SM_GYCAPTION) + 
GetSyBtEmMerrlcs(UM_CYFRAME)): 
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tfendif 


I 


myResult = SetWlndowRgn{ 

(* *theWindo\#Object) .fWindow* 

(**inyAppData)-fWlnHRGN* true] i 
if (myResult =0) 1 
// SctWindowRgn fiiiltd 

DeleteObject [ (*’*myAppData) *fWinHRGN): 
(**i!iyAppData) .fWinHRGR “ NULL; 
goto bail: 

] 

I 

// repeat with drag region picture 

tnyErt - MediaGetFubIicInfo{iiiyHandler ♦ 

FOUR_CHAR_COBE{-skdrV). myPlcture* HULL]; 
if CmyErr != noErr) 
goto bail; 

// convert it to a region 

rayErr = QTSkin_ConvertPictureToRegion(myPicture. 

ii(* ‘inyAppData) /fDragRegion): 
if (nyErr >= noErr) 
goto bail: 

// scale that region so the window scales with the movie 
myEtr = TransfonnRgnClimyHatrix* 

C**myAppData).fDragRegion}: 
if (myErr != noErr) 
goto bail; 

// copy the content region into the stmciurc region 
(**myAppData)^fStructRegion = NewRgn{): 

MatCapyRgnC (* *EnyAppDataT*fContentRegion* 

{* *tnyAppData). fStructRegion); 


bail; 

if (myPlcture ]= NULL) 

DisposeHandle((Handle)t(iyPicture): 


Specifying a Custom Window Shape 

As weVe seen, it’s child’s play on Windows operating systems 
to specify a custom window shape: just pass the sliape (as an 
HRGN) to SetWindowRgn. On the Mac, ifs quite a bit more 
complicated. We need to write a custom window definition 
procedure and attach it to any skinned movies tliat the user opens. 
In our framework function QTFrame_OpenMovielnWindow, we’U 
add a few Mac-specific lines before the existing call to 
QTFrani0_CreateMovieWindow; 

#if TARGET_OS_MAC 

// create a new window to display Lhe movie in 
if {QTSkln_I sSkinnedMovle (layMovie]) 
myWlndov = QTSkin_CreateSkinsWlndow(}; 
else 
#endif 

myWindow “ QTFirame„CreateMovieWindaw{}: 

On Macintosh computers, QTFrame_CreateMovieWindow calls the 
Window Manager function NewCWindow to create a standard 
document window For skinned windows, we need to call 
CreateCustomWindow, as shown in listing 7 


Listing 7; Opeiiiiig a wind0Wwilfa a custom shape_ 

Q^ISkin_CreateSkins Window 

WindowRefefence QTSkin^CreateSkinsWindow (void) 
i 

WindowPtr myWind qv “ NULL; 

WindowRefefence myWlndowRef = NULL; 

Rect myRect = <10, 60, 200, 2001; 


return(myAppDeta); 

1 


// call CreateCustomWindow to create a window using our custom window 
defproc 

CreateCustoraWindowt&gUefSpec, kDocuraentWindowCIass, 
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kWindowNoAttributes . ^myRect, ^niyWlndow)» 
if (rayWlndow 1= HULL) I 
// get the “window refcmnee" for this window 
myWlndovRef = 

QTF r a me_Get Wind o^jRe f e r e nc e F r omW ind o v (ay Win d ow ] : 

// create a new window object associated witli the new window 
QTFrame_CreatoWindowObjeGt[ayWindowRef); 

] 

return[myWindowREf)* 


This call to CreateCustomWindow asks for a docLiment 
window with no special attributes. (The rectangle parameter is 
arbitrary, since we'll change tlie window size later.) llie window 
definition procedure to be used to handle the custom window is 
specified by the &gDefSpec parameter, which is a pointer to a 
window definition specification, declared like this: 

struct WindowDefSpec [ 

WindowDEfType 
union i 

WindowUefUPP 
Void 
Short 
1 u: 

1 : 


The defType field specifies which member of the union u we want 
to use. In the present case, we want to use the clefProc memlDer, so 
we set defType to kWindowDeProcRr. And we'll set the defProc 
member to a universal prtxredure pointer to our aistom window 
definitiem procedure. We initialize the gDefSpec global variable in 
the application start-up code for Ql'Skins, by culling tlie QTSkin_lnit 
hinction defined in Listing 8. 

Listing 8: Setting up a window definition specification 

QTSkii]_Jnit 

void QTEkiTi_Init (void) 

[ 

// sot up the window dofmiiion specification stniciure 
gDefSpec,dEfTyps “ kWindowDefProePtr: 

gDefSpec.u.dEfProc = NEwWindc3wDefUPP{QTSkln_SkinWindowDef}: 


Writing a Custom Window Definition Procedure 

On Macintosh operating systems, die appearance and 
iiehavior of our skinned movie windows are determined by 
QTSkin_Sk3nWindowDeh our custom window definition 
procedure. QTSkin_SkinWindowDef is declared like this: 

static PASCAL_RTN long QTSkln^SklnWlndowDEf 

(short theVarCode, WindowRef theWlndoWn 
short theMessage. long theParam): 


Here, theMessage is a window definition message that indicates 
which ta.sk the window definition procedure is to perform. 
These are the common window definition messages: 


enuim [ 


kWindovMsgDraw 

= 0* 

kWindowMsgHitTest 

= 1* 

kWindowMsgCalculateShape 

= 2* 

kWindowMsglnitiaLizE 

“ 3* 

kWind owMs gCleanUp 

- 4* 

kWind owMs gD r awGrowOutline 

= 5* 

kWl nd 0 wMs gD r awGr o wB o x 

= 6 * 

kWitidowMs gGe t Featurss 

’ 7* 
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kWindovMsgGetRegion “ 8, 

kWltidovMagDragHlllte - 9. 

kWindowMsgModified = 10* 

kWindovMsgSrawInCurrentPort ”11, 

kWindavMs gSetupProxyD ragl]iiage= 12, 

kWlndowMsgStateChangsd ^ 13* 

kWindovHsgHeasureTltXe ” 14* 

kWindowMsgGetCrowImageRegion =19 


We can ignore most of these messages in our procedure. For 
instance, our skinned movie windows don't have grow boxes, 
so we can ignore the kWindowMsgDrawGrowOutline and 
kWindowMsgDrawGrowBox messages. In fact, well need to 
handle only three of these messages: kWindowMsgHitTest, 
kWindowMsgGetFeatiifes, and kWindowMsgGetRegion. 

When we receive tlie kWindowMsgGetFeatures message, we 
need to return (through theParam) a value that indicates the 
capabilities of our custom window definition procedure. Really ah 
C5ur custom prcx:edure can do is return information about various 
window regic3ns. So well set the features information like this: 

case kWindowHfigGetFeaturEfi: 
if (theParam [” OL) 

‘ (OptiotiBita *) theParaiD = kWindciwCeiiGetWindowRegiDii; 
return[l); 

The meaning of the reaim value of our custom window definition 
procedure varies, depending on the message the procedure is 
liandling. In tills case, the doaimentation tells us to return 1. 

When we receive the kWindowMsgHitTest message, we need 
to return one of diese values, indicating which region of the 
movie (if any) w'as clicked in: 


enum I 


wNoHit 

= D. 

wlnContent 

- 1. 

wlnDrag 

- 2. 

wlnGrow 

” 3. 

winGoAway 

= 4. 

wlnZootnln 

= 5, 

wlnZootnOut 

- 6. 

wInCollapseBox 

- 9. 

wlnProxylcon 

= 10 


With this message, theParam contains the coordinates of the 
mouse click, which we can extract like this: 

myPoint.v = HiWord(thEParam): 
myPoint.h ^ LoWord(theParam)■ 

This point is in global screen coordinates. Our regions, liowever, 
ate stored with the upper-left comer set to (0, 0), So we need to 
map myPoint into the window's local coordinate system, as follows; 

GetPort(&niyPort) : 

SEtPortWindowPott(theWindow); 

myLocal = myPoiiit; 

GlobalToLacal (SeinyLocal) ; 

MacSetPort(myPort): 

The GlobalToLocaf function maps the specified point into the 
coordinate system of the current graphics port, so we need to 
make sure that our custom window is the current graphics port 
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(taking care to save and restore the previous current port). 

Now that weVe got a point Icxral to the skinned movie window, 
we can use the PtInRgn function to do the required hit-testing: 

if (Pt1nR^n £ myLo cal, £‘* myAppDat a)* fD ragRegion)} 
return(wInDrag}: 

If (PtInRgn (myLocal, '^myAppData) * fContentRegion)) 
return(wInContent): 

return(wNoHit); 

We first look to see whether the sf)ectfied point is in tlie drag 
region. Lf not, we look to see whether it’s in the content region. 
If the point is in neither region, we indicate that no hit occurred. 

When we receive the kWindowMsgGetRegion message, 
theParam is a pointer to a structure of type GetWindowRegionRec: 

struct GettflndowReglonRec ( 

RgnHandle witiRgn: 

WindowRegionCode reglonCode: 

h 

The regionCode field indicates which region we are supposed to 
return (through the winRgn field). Our skinned movie windows 
have only three interesting regions, the content region, the drag 
region, and the structure region (which is typically identical to 
the content region). So well respond to only three values for the 
regionCode field: kWindowContentRgn, kWindowDragRgn. and 
kWindowStmctureRgn. 

The region whcxse handle we return in the winRgn field is 
supposed to be specified in global screen coordinates. Our 
stored regions, however, are specified in coordinates local to the 
client region of the movie window. So we need to offset those 
regions before we return them from our window definition 
procedure. First, then, we need to figure out the global 
coondinates of the top-left corner of the window, like this: 

GetPort(fanyPort); 

SetPortWindowPort(theWindow): 

GetPortBounds(GetWlndowPurt(theWindow), irnyPortBoundfl}; 

rayTopLeft.h ^ myPortBounds.left: 
myTopLeft.V " myPortBounds.top; 

LocalToGlobalC&tnyTopLeft): 

MncSetFort£iiiyPort): 

Then we need to offset any of the regions we pass back. For 
instance, well pass back the window’s drag region like this: 

MacCopyRgn((*'myAppOata).fDtagRegion, myRgnRec■>winRgn): 

Mac OffeetRgn(myRgnRe c■>wlnR gn, myTopLeft.h. myTopLe ft.v J: 

Listing 9 shows our complete window definition procedure 
for skinned movie windows. 

Listin g 9; Ha ndlfaig skinned movie window messages _ 

QTSkin_SkinWindowDef 

static PASCAL_RTN long QTSkin„SkinWindowDef 

(short theVarCode, WindowRef theWindow, 
short theHessage, Long theParam) 

[ 

tfpragma unused(thaVarCode) 
awltch (theMessage) I 


case kWindo\^sgInitialize: 
case kWindo^irflsgCleanUpt 
case kWindowMsgifrawGrowOutline: 
case kWlndowMsgDrawGrcswlox; 
case kWindowMsgOraw: 

// nothing here 
break; 

case kWlndowMsgHltTestr i 

ApplicationDataHdl myAppData “ NtliL; 

Point myPoint: 

Point myLocal; 

GrafPtr myPort; 

myAppData = 

(Applic a tionD a t aHd1}QTF rame_GetAppD at aF romWind ow 
((ITFrameJ^^etWindowRefatenceFroiiiWindow(theWindow)); 
if (myAppData “ NULL) 
return(wNoHlt); 

// on entry, thePiim contains the mouse location in global screen coordinates 
myPoint.V = HiWord(theParam)i 
myPolnt.h ^ LoWord(theParam): 

// the content and drag regions are offset relative to the window origin 
GGtPort(&myPort); 

SetPortWindowPort(theWindow); 

myLocal ” myPolnt: 

GlobalToLocal(fimyLocal); 

MacSetPort(myPort): 

// look first to see If the mouse event is in the drag region; 

// it takes precedence over the content region 
If (PtInRgn(myLocalI (‘'myAppData).fDragRegion)) 
return (wlnDrag); 

if (PtInRgn(myLocal, (‘‘myAppData).fContentRegion)) 
raturti(irflnContunt): 

return(wNoHit); 

1 

case kWindowMsgGetFeatures; 
if [theParam 1“ OL) 

‘(OptionBits *)theParam ^ kWindowCanGetWindowRegian: 
return ( 1 ) ; 

case kWindowHsgGetRegion: i 

GetWindowRuglonRec ‘myRgnRec ^ 

(GetWindowReglonRec ‘}theParain; 
AppXlcatiouDataMdl myAppData = NULL: 

GrafPtr myPort; 

Rect rayPortBounds: 

Point myTopLeft; 

myAppData = 

(Ap p1Ic a tlouDataHd1)QTFra me^Ge tAp pDat aP i omWlnd ow 
{QTFrame_GetWindowfiefetenceFroraWindow(theWindow)): 
if (myAppData = NULL) 
break; 

// get the top-left comer of the window, in ^obal coordiiutes 
GetPortCfiimyPort); 

SetPortWindowPort(theWindow): 

#if TARGET_API_MAC„CARBON 

GetFortBounds(GetWindowPort(theWindow). imyPortBounds); 

Jfelae 

rayPortBounds ^ theWindow->portRect; 

^^endif 

rayTopLeft.h = myPortBounds*left; 
myTopLeft.v = myPortBounds.top; 

LocalToGlobal(^myTopLeft); 

MaeSetPort(myPt>rt); 

switch {myRgnRec‘>regionCode) t 
case kWindowTitleBarRgn: 
case kWindowCloseBoxRgn; 
break: 
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case kVindowDragRgn: 

MacCopyRgn((*‘myAppData).fDragRegion, 

myRgnRec->vinRgn): 

MacOffsetKgji (myRgnSec ‘ >viTiRgn, myTopLeft * h * 

myTopLeft.v); 


break: 


case kWindoTifCoiitentRgn: 

MacCopyRgn (f ^ *tnyAppData). fContentRegion, 

myRgnRec->winRgn): 

Ma c OffE etRgn(rayRgnRe c■>winRgn, myTopLeft.h * 

rayTapLeft.v): 


break; 


case kWindowStmctureRgn: 

MacCopyRgn f C*'myAppData).fStructRegion, 

myRgnRec->vinRgn): 

MacOffsetRgn(myRgnRec'>wlnRgn. rayTopLeft 

niyTopLeft*v): 


break: 


default: 

break: 

) 


returnEnoErr); 

I 


default: 
break; 

1 


return(OL): 

1 


Handling Dragging on Windows Computers 

Earlier we saw how^ to assign a custc^m window^ shape to a 
movie on Windows operating systems, by caQing SetWindowRgn. 
We still need to see how to handle window dragging on Windows. 
Let’s begin by reviewing briefly liow our window pnK'eduie ftjr 
movie window.s prtJCesses tlie mess^^es it receives, Listing 10 shows 
a snippet from QTFrame_MovieWndProc. First of all, it fills out an 
MSG structure and translates the Windows message into a 
Macintosh event by calling WinEventToMacEvent. Then it passes the 
Mac event to the application function QTApp_HandleEvent. Then, if 
QTApp^HandleEvent did not handle the event, 
QTFrame_MovieWnclProc passes the Mac event to MClsPlayerEvent. 

Listing 10: Sending Windows messages to the movie 

controller_ _ 

QTFninic_MovicWntIPn)C 

MSG myMsg - tOl : 

LONG my Points = GetMessagePosO : 


With skinned windows, the drag regions and the content 
regions virtually always overlap, so we need to prevent the movie 
controller from getting any mouse dicks that are in the drag region 
(since it would likely interpret them as clicks in the content 
region). We can do this quite easily by liaving QTApp_HandleEvent 
look to see whether die event ifs passed is a mouse click in the 
drag region and, if k is, return true. Listing 11 show^s the QTSkins 
version of QTApp_HandleEvent. Note that this code is 
c'onditionaiized for Windows applications only, since on 
Macintosh the window definition procedure is responsible for 
finding dicks in the drag region. 


Listing 11: L ooking for drag reg ion cMcks (Win dows) 

QTApp^HandlcEvcnt 

Boolean QTApp_HandleEvent (EventRecord *theEventJ 

I 

iflf TARGET_0S_MAC 

jp ra gina unus ed (theEvent) 

#endif 

Boolean inylsHandled “ falfie; 

#if TARGET_0S_W1NB2 

ApplicationDataHdl rayAppData ^ (ApplicationDataHdl) 

QTFraiiie_GetAppDataFi:oinFrontWindow (); 

Point rnyPoint: 

if EtbeEvent = HULL) 
goto bail; 

if EtbeEvent'>>fhat = raouseDown) | 
tnyPoint ^ theEvent->wliere; 

GlobalToLocal(&rayPolnt): 
if EmyAppData 1“ HULL) 

If (PtInRgnEmyPoint, (^ *myAppData).fDragRegion)) 
mylsHandled ^ true; 

I 

#endlf 

bail: 

return{raylsHandled): 

I 


So far, then, weVe managed to prevent the movie controller 
associated witli a movie window from getting clicks in the 
window’s drag region. Now' we need to actually handle those 
clicks. On Windows, we can look for messages of type 
WM_lBUTTONDOWN and see if they are in the drag region. If 
they are, we want to trick the default window procedure into 
thinking that the clicks are on the title bar, so that the default 
window procedure will handle tlie dragging for us. We can do 
this by sending a message of type WM_NCLBUTTONDOWN to the 
default window' procedure, like iliis: 

SendMessageEtheWnd. WK_HCLBUTT0m>0WH, (WPARAH)BTGAPTION. 

HAKELPARAME5, 5)): 


rayHsg.hwnd ” theWnd; 
myMsg.message = theMessagc: 
niyMsg.uParacn = wParam; 
royMsg,lParara = 1Param; 
myMag.tirae ” GetMessageTiraE(); 
myMsg.pt.Jt = LOWORD(myPoints); 
myMsg.pt.y = HIVORD(rayPoints); 

// ininslatc a Windows event to a Mac event 
WinEventToMacEvent(&myMsg, &myMacEvent); 

// let tlie application-specific code have a chance to iniercept the evetii 
mylsHandled = QTApp_HatidleEvent E&iiiyMecEventl : 

if the Mae event to the movie contmller 
if (IraylsHandled) 
if ErayMC 1= HULL) 

If £[Islconic EtheWnd)) 

raylsHandled = MCIsPlayerEventCmyMG, 

(EventRecord *)^myMacEvent): 


The WM_NCLBUTTONDOWN message reports a button-down 
event in a non-chent area of a window. The first parameter 
indicates which part of the w indow is directly under the cursor 
hot spot at the time of the click. In our case, we w-ant to say that 
the click occurred in the Lille bar (indicated by the HTCAPTION 
constant). The second parameter indicates the location of die 
cursor hot spot, in coordinates that are relative to the upper-left 
corner of the screen. As best I can tell, the default window 
procedure ignores that parameter when the first parameter is set 
to HTCAPTION. So well pass an arbitrary value of (5, 5), Our 
complete left-button click handling is shown in Listing 12. 
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14sting 12: Handling drag re^a dicks (Windows) 

QTFranie_Mo™WndPTioc 

case WM„LBUTTONDOWN; 

// hiindk potential dicks in window drag negion; 

// if wc gpt one, inap it into a click on the title bar 
if (QTSkin^IsSkinnedtlovieCiiyHovie)} 

if CQTSkin_IsElragCliGk(myWindovObject, iParain)] [ 
SendMesEagG{theWnd. WM_MCLBUTTONDOWN, 

CWPARAM)HTCAPTION. MAKELPARAM(5, 5)): 
raylsHandled = true^ 


// do an>' application-specific mouse-tmitnn handlingj 
// btit only if the message hasn't already been handled 

if (ImylaHandlGd) 

QTApp_HandleContentClick Cthetfnd. &iriyMacEvent); 
break; 

The only thing left is to consider the definition of 
QTSkinJsDragClick, which we chII in Listing 12 to determine 
whether the specified point is in the drag region of the 
skinned movie window. Here we have several possibilities. 
We saw above that our version of QTApp^HandleEvent returns 
true if the specified event is a mouse-down event in the 
window's drag region. So we could just use that function. 
Alternatively, we can convert the Mac-style drag region (saved 
in our application data record) to a Windows region (of type 
HRGN) and call the Windows function PtinRegion to see 
whether the specified point is in that region. That’s the 
strategy we’ll use here; Li.siing 13 shows our definition of 
QTSkinJsDragClick, 

Listing 13: Finding drag region clicks (Windows) 

QTSkin IsDnigClick 

TAftGET_OS_WIN32 
Boolean QTSkin_IsDragCllck 

EWindowObject theWindowObject, LONG iParaci) 

I 

WindovObJect tnyWindowObject = NULL: 

ApplicationDataHdl myAppData - NULL: 

HRGN niyRe&ion “ NULL; 

POINT ^Point; 

Boolean isDragClick = fal&e; 

myAppData ^ [ApplicationDataHdl) 

QTFraiiG_detAppDataE romWindowObject(theWindowObject); 
if (tDyAppData != NULL) [ 
inyPoint.x ^ LOWORD(lFaram3: 
inyFoint^y ” HlWORUdParaBi); 
iny Region = NacRegionToNativeRegion 
((* *rayAppData),fDragRegion): 
if (PtlnEegionfmyReglon. toypolnt.x, rayPoiut.y)} 
laDragClick = true; 

DeieteObject[myRegion); 

] 

return(IsDragClick); 

I 

^iendif 


TTe IParam parameter that w^as passed to WM_LBLrTTONDOWN 
(which we also pass to QTSkinJsDragCtick) specifies a point in 
cxx)rdinates that are loc^l to the client area of the window. As a result, 
we don’t need to offset the drag legion in Listing 13- 

So now' weVe completely handled a click in the drag region 
of a .skinned movie window on Windows. 


Shutting Down 

When the user closes a skinned movie window, we need to 
deallocate any memory used for displaying the movie in a skin. 


In particular, we need to dispose of the window regions that 
we’re storing in the application data record. Listing 14 shows the 
definition of QTSkin_DumpWindowData, which is called by 
QTApp_RemoveWindowObject. 

listing 14: rJeaning up wh en a skinn ed window is dosed 

QfSkin_DumpWmdowDaita 

void QTSkln_DumpWlndowData (WlndowObJect theWiudoyObjeEit) 

[ 

ApplicationDataHdl myAppData = NULL; 
myAppData = [ApplicationDataHdl) 

QTF r aTiie_GGtAppDaiaFrotii¥lud owOb j ect {theWind owOb j e c t): 

If (myAppData !- NULL) [ 

if [(* * myAppData).fCont entRe gion [ = NULL) 

DispoaeRgn((’’myAppData).fContentRcgion): 
if ((*'ttiyAppData).fDragRegion != NULL) 

DlsposeRgnC t*’myAppData).fDragRegion); 
if ((’’myAppDate),f3tructRegion NULL) 

DisposeRgn((’’myAppData)*fStructRcgion); 

DiflposeHandle[(Handle)myAppData): 

(*’theWindowObj ect).fAppData " NULL: 

1 

1 

You’ll notice that we didn’t do anything to free up the memory 
addressed by (**myAppData).fWinHRGN. The documentation for 
the SetWindowRgn function indicates that the operating system 
owns the region we pass It; this means that we don’t need to call 
DeieteObject on that region. 

When our application shuts down, we need to deallocate 
the universal procedure pointer contained inside of the gDefSpec 
structure. Listing 15 shows how we do this. 

Lifting 15: Cleaning up at application shut-down^.. 

QTSkin_Stop 

void QTSkln_Stop (void) 

I 

// dispose of tlie window prsxedure liPP 
if [gDefSpec,u,defProc f- NULL) 

DleposeWindowDefUPP(gDefSpec,u.defFroc): 


CDNCXUSION 

If you’ve made it this far, you deserve a pat on the back. 
We’ve had our usual dose of new QuickTime APIs, hut weVe 
also had a big gulp of low-level window management. On the 
Macintosh, we had to write a custom window definition 
procedure in order for our application to handle skinned 
movie windows. And on Windows, we had to tinker with our 
application’s event-handling to support skinned movie 
window dragging. But the payoff for all this work is 
tremendous, precisely because skinned movies are such 
great stuff. As weVe noted, the movie author now has 
virtually complete control over the appearance and behavior 
of movie windows. The movie interface has become part of 
the movie content. The medium is now pan of the message. 

Credits 

Special thanks are due to Jim Batson for reviewing this 
article and providing some helpful comments. Thanks are also 
due to id Media, Inc. (http://www.idmediainc.net) for permission to 
use die picture of the movie in Figure 3 Hi 
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PROGRAMMER'S 

CHALLENGE 


by Bob Boomtra, Westford, MA 


Carribean Cruising 

1 love .sailing. That is, most of the time I love it, in between tlie 
moments when Im terrified in an exhilarating sort of way 1 don’t 
own a boat, wliich has aOowed me to avoid both of the two favorite 
days of a boat owner's life - the day he buys the boat, and the day 
he sells the boat. Most years I'm a tw^o-week-a-year sailor, renting 
small to medium size boats on inland lakes during summer 
vacations. 

But this year we did something different. We decided to charter 
a sai]lx>£it and spend a week in the US. and British Virgin Islands. 
"Ilianks to Captain Jerry and Chef Christine Miller on a 5! Beneteau, 
the Rusty Nail n <yachLs-on-line.a)m/rustynail2/>, we had a 
wonderful week sailing, snorkeling, (drinking - I’d forgotten how' 
many truly excellent drinks can he made with mm) and dining our 
way around St John, Tortola, Norman Island, Viigin Goida, Marina 
Cay and several other islands. 

So why am I telling ytxi this? Not to arouse efTV 7 , certainly not. 
No, I’m telling you this because the Augiust Challenge Ls based on 
sailing. Yrxir task this month is to write code that will efFidently sail 
a simulated bo^at anxmd a set of obstacles, through a specified 
sequence of marks. 

The prototyfx: for the code you should write is: 

typedef struct Position [ 
long XI t pfisitivic x is East 7 
long y: t p<isitivo y Ls Nf^th 7 
I Position; 

typed 0 f doub 1 e Direc tlon; t tkjtkwise frrjm north, in nidiuts V 

typedef struct Volocity f 
Direction direction; 
double speed; 

/• X vtlodt)' is speaf sm(diittiiori) 7 

r y vtiodt)^ is spt^£X)s(directiori) 7 
I Velocity; 

void InitCa r ribeanCruise( 
short nuinberOfKarks, 

Pasltion mark!]i 

t must pass tliroitgji marfcfi] (br radi i in rum 7 
double tolerance, 

r must pass within this distmcc of each maik 7 
dotibie into grot in nlnterval 

r amcHini of lime between calls to Cruise, in seconds 7 

): 

Boolean /*dunc7 Cruise ( 

Position boatLocatlon, t btwi poMiion at rhe stail tif this time segment 7 
Velocity hoatVelocity. T l^>ai vckxity at the start of tliis time segment 7 
Velocity wlndVelocity, f* true wind vckxity at this location and time 7 
double currentTiine * t time since cruise start, in seconds 7 

Direction “targetBoatBirection. 

r commanded boat direction 7 
Direction *sailTrlni 

t ctjmmandcd sail i]ini,0..Pl/4, measured as angk off the stem, 
in tite direction away horn tlic source of the wind. 

Aetna] soP ixjsitira is a function of trim and wind direcUon. 7 


void TertiCarribeanCntlse (void): 


The Challenge works like this. First, your lnit(;)arribeanCnjise 
routine is called, providing you with a description of the cx>urse to be 
followed. You will need to pass tlirough tlie specified marks in 
sequence, approaching each within a specified distance tolerance. 
Tlien your Cruise routine is ailed repeatedly, at time intervals of 
integrationinten^al, until you complete the course. Finally your 
TermCambeanCruise routine is called, where you should return any 
dynamically allocated memory. 

Willi each Cruise call, you are given tlie current boatLocatlon 
and boatVelocity along with the current WindVelocity for your 
location at the currentTlme. You liave two controls for the Ixiar, the 
helm and the saifTrim. For simplicity we're going to tieat your boat 
as if it has only cjne sail - no need to separately trim the main and 
the jib. Our simplified sail trim model leLs you control the maximum 
amount the sail can be lei out, from 0^ off the stern (tight trim) to 90^ 
off the stern. The sail always mtwes away from the stem m the 
direction aw^ay from the source of the wind, ckxrkwise off the stern 
when the wind is from starlxiard (right of the boat), and 
cxxinterckx:kTvise when the wind is from port (left of the boat). 

High Mdiw sailing models use aimplicaled vekxity prediction 
programs to detemiine boat speed as a function of wind and sails, 
but we'll use somediing simpler. When sailing into the wind (you 
ainnoi sail directly into the wind, but you can sail up to 45'^ off the 
%vind direction in our model), the greatest sailing force is provided 
with the sails tight, if off die stern. As yt>u fill off die wind, greater 
ilirusi Ls provided l>y ei^ising the sails (xii. When the wind is diiecdy 
astern (behind you), letting the sail t>ut a full 90° provides the 
greatest thrust. 

As ctxmterinmitive as it miglit seem, ytiii actually s^til Lister when 
going upwind. This is becaLise the motion of the baat actually 
incTeases die apparent speed of die wind. You can take my word for 
it, or ycxi can do a litde vector arithmetic to ainvince pursell'. 
Similarly going downwind, the force of the wind on die toat actually 
approaches zero as the boat speed gets closer to the true wind 
speed, Inducing the apparent wind speed. Of course, die resistance 
of the water prevents the boat from actually reducing the apparent 
wind speed to zero. 

Enough about sailing, back to w^hirt you need to do. For each 
call to Cruise, you need to return the direction you w;ini the boat 
to move (targetBoaiDirecdon), and how you w^ant to trim the sail 
(sailTrim). There are limits on how quickly the boat can turn, so 
you might not actually attain the targelBoalDireaion in one 
integration interval. A.s for the sailTrim, if you ease the sail too 
much, it will luff and provide less (or perhaps no) force. If you 
keep it too tight, you’ll also get less force from the wind and will 
go more slowly. The specifics of the velocity model will be 
included in the test code provided with the problem — see 
www.mactech.com/progchallenge/ for details. 

Your objective is to sail dirough the marks as quickly as 
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possible. The winner will be the entry that compietes the course 
in tlie minimum simulated time, idter adding a penalty of one 
simulated secxjnd for each millisecond of execution time. The 
Challenge prize will be divided between the overall winner and 
the best st'oring entry from a contestant that has not w^on the 
Challenge recently. 

This will he a native PowerPC Challenge, using the 
CodeWarrior Pixs 6 environment. Solutions may be coded in C or 
C++, You may prrjvide a solution in Java instead, provided you also 
provide a test driver equivalent to the C code provided on the web 
for this pioblem. 


Three Months Ago Winner 

Nine contestants, including many first-time participants, 
submitted entries for the May Klondike Challenge, Tliis Challenge 
required readers to create a Klondike solitaire game using the 
RealBASlC development environment. Unlike most Challenges, 
performance played no role in evaluating the entries. Instead, the 
evaluation was based on features, lioth featuies specified in the 
problem statement, and extra features that readers were invited to 
add. There were several excellent solutions submitted, and it was 
difficult to select a w'innei Congratulations to Peter Tmskier (San 
Mateo, CA) for winning the Klondike Challenge, 

Peters solution satisfies all but one of the features specified in 
the problem. He prov ides a high quality representation of the game 
state; allows cards to be played by dragging them to their 
destination; highlights a legal destination when a card is dragged 
over it; provides an undo/redo capability; includes menu items for 
saving, replaying, and restarting games; and allows cards to l^e 
turned over in increments of one or three. As metros, he provides 
st jund effects, including a shuffle sound at the start of a new^ game, 
a celebratory sound following victory and feedback when a card 
was clicked. He displays the tableaus in staggered fashion, so it is 
possible to see how^ many cards remain to be uncovered (not all 
entries did this, which made play more difficult). Peter displays <ards 
being dragged translucently so it is possible to see wliat is under the 
card as it Is dragged. He allows cards to be played to their tinaf 
destinations by clicking as well as dragging. He provides extra 
preference options, including control over whether strict or loose 
rules apply to game play and scoring. And he provides preference 
control over the background and highlight colors, Peter's entry 
automatically detects a win when all cauls have l^een uncovered and 
made playable, but before the cards are actually played. Finally Peter 
provides a help Function. 

The second-place entry by Noah Desch also has some 
interesting features. He provides extensive preference options for 
controlling scoring, including subtracting points as time passes, 
subtracting points tor multiple passes tlirough the deck, and 
subtracting points as a penalty for using the undo/redo feature. His 
entry displays not only the score, but the ela|7sed time, and sound 
effects notify the user when a time penalty is being applied. His 
' preference panel displays a rollover explanation of what each item 
does. Noah displays the top ten tiigh scores and gives you an option 
to clear those scores. And he provides four choices for card deck 
style and three choices for the game board. Noah also provides 
warnings to the user when he quits a gaine that is in progress 
without saving it. Noah's entry was targeted at Mac OS X, but it ran 


under 9,1 as well It could easily have been the winner 

Closely following Noah in the admittediy sub^ctive scoring is 
Presidential Klondike, by Will Leshner. W'ill provides all of the 
specified features, plays sound effects during tlie game, and plays 
the U.S. national anthem as a bonus after a win. He also provides 
the convenience of automatically ttiming over the next card in a 
tableau when a card is played. Will provides preference control over 
sound, a scoring time penalty and animation. He aLst^ provides a 
folder of saved games developed as Ills spouse bec^ame addicted to 
tlie game during testing (sorry about iliat. ©). 

Ticxl in tlie soaring with Will, Thomas Reed also submitted an 
excellent entry. Tliomas provides preferenc’e control over the game 
and scoring rules, a separate "hard ’ss” optic3n to set them all, and a 
slider control over the number of undo/redo levels allowed He 
provides ballcKin lielp. And you can change the background liy 
placing a gif file in a Backgrounds folder. Finally Thomas provides 
a “play out” option, that will complete the game for you once all of 
tile cards liave lieen expased. 

Hounding cut the top five entries is the submission from 
Jacqueline Landsman Gay. Jacques entry would liave scored even 
higher, but it was written in MeiaGiid rather than RealBASlC, Given 
the unusual rules for this Challenge, 1 decided to accept the entry 
even though I couldnt rebuild the application (not liaving access to 
MemCard), and instead withheld evaluation points for not meeting 
one of tlie problem requirements. The graphics in the are 
excellent, it has a high score list, it provides options for the and track 
and playing surface. It also has attractive feamres cited for some of 
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the earlier entries, like a shuffle sound, play by double-clicking 
caids, automatically detecting a win, and playing a tribute when a 
win is detected. 

1 also asked people for feedback about using RealBASIC or 
other non-C environmenLs for the Challenge, and the reaaion was 
quite positive. Many new readers dedded to enter, although few 
traditional Challenge partidpanLs did so. Fm inclined to try this again 
sometime. If you have additional thoughts on the topic, let me know 
at pn:>gchallenge@mactechxoni. 

The table below lists, for each of the solutions submitted, the 
pc^ints earned in various categories: features specified in the problem 
statement, extra game play and help features, display and sound 
features, extra scoring and preference options, and a subjective 
assessment of style and quality of play As usual, the number in 
parentheses after the entrant’s name is the total number of Challenge 
points earned in all Challenges prior to this one. 


Name 

Specified 

Play 

Display 

Scoring 

Style 

TOTAL 


Features 

Sl Help & Sound 

&Prefe 

Points Points 

Peter Truskier 

50 

6 

6 

1 

10 

73 

Noah Desch 

53 

1 

5 

6 

6 

71 

Will Leshner 

53 

1 

4 

2 

10 

70 

Thomas Reed 

55 

3 

4 

3 

7 

70 

Jacqueline landman Gay 

42 

6 

6 

4 

8 

66 

Heniik Rintala 

47 

3 

5 

1 

4 

60 

Bruno Dlubak 

50 

0 

3 

0 

6 

59 

Ernst Munter (751) 

32 

3 

2 

0 

4 

4] 

Thomas J. Cumungham 5 

0 

0 

0 

0 

5 



Top CoNTESTAivrs ••• 

Listed here are the Top Coniestants for the Programmer’s 
Challenge, including everyone who lias accumulated 20 or more 
points during the past two years. The numl^ers telow include points 
awarded over the 24 most recent contests, including points earned 
by this month’s entrants. 


Rank 

Name 

Points 

Wins 

Total 



(24 mo) 

(24 mo) 

Points 

1. 

Munlei; Ernst 

284 

11 

751 

1 

Eieken, Willeke 

83 

3 

134 

3. 

Saxton, Tom 

69 

2 

1S5 

4. 

Tayloi; Jonathan 

56 

2 

56 

5. 

Wlhllxirg, Ches 

49 

2 

^9 

d 

Shearei; Rob 

55 

I 

62 

J 

Maurer Seiiiastiaii 

38 

1 

108 

a 

Iktskiei; Peter 

20 

1 

20 


AND THE Top CONTESIANTS LOOKING FOR A RECENT WlN 
In Older to give some recognition to other participants in the 
Challenge, we also list the high scores for contestants who have 
accumulated points without taking First place in a Challenge during 
the past two years. Listed here are all of those contestants who have 
accumulated 6 or more points during the past two years. 


Rank Name 

Points 

Total 


(24 mo) 

Points 

9. 

Boriiig, Kandy 

32 

142 

m 

Schotsman, Jan 

M 

14 

u. 

Sadetsky Gregory 

12 

14 

12. 

Nepsund, Ronald 

10 

57 

13. 

Day Mark 

10 

30 

14. 

Jones, Dennis 

10 

22 

15. 

Downs, Andrew 

10 

12 

16. 

Desch, Noah 

10 

10 

17 

Duga, Brady 

10 

10 

18. 

Fazekas, Miklos 

10 

10 

19 

Flowers, Sue 

10 

10 

20. 

Straut, Joe 

10 

10 

21. 

Nicolfe, Ludovic 

7 

55 

22. 

Flala, Ladislav 

7 

7 

23. 

Leshnei; Will 

7 

7 

24. 

Millet; Mike 

7 

7 

25. 

Widyatama, Yudlii 

7 

7 

26. 

Heithax-k, JG 

6 

43 

There am three ways to earn points: (1) .sa.)ring in the top 5 of 


any Chaileoge, (2) being the first person to find a bug in a published 
winning solution or, O) being the first person to suggest a ChaOenge 
that 1 use. The points you can win are: 


1st place 20 points 

2nd place 10 poims 

3rd place 7 ixiims 

4th place 4 points 

5th place 2 points 

finding bug 2 |X)inis 

suggesting Cliallenge 2 points 


liere is Peter's winning fOondike solution: 

Klondike_ptniskief, rbp 
Copyright © 2001 
Peter Tniskier 

Window 1 

Windowl. newGame: 

Sub tiGwCaMef) 

Canvas1.newGane(flip3) 
gameOver = false 
gamellnderWay = false 
pushNewState() 

End Sub 

Witidowl, Open t 
Sub OpenO 

dim i as integer 

canvas1.GetDeptb(32} 
canvasl.repaint 
newGaine () 
shows CO re = true 
windowOpen - true 
aboutDialog.close 
End Sub 

Windowl.Canvas1,KouseDrag: 

Sub MouseDragCX As Integer* Y As Integer) 
dim as integer 
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//are we dragging from the deck? 
if Ene.theDeck.topGardDragging then 
jBe.dragObj.matingRect.xOL “ x - me.dragObj.aouseOffsetX 
me.dragObj.matingllect.yUL = y - iiie,dragObj^mouseOffsetY 
me^dragDbj.tnatingRect.xLR = me-dragObj .matlngRect .xUL + wl 
me.dragObj,matitigRect,yLR ” rae.dragObj^nmtingRect.yllL + hi 
n “ uBoundCme^theTableatis) 
for 1 = 0 to n 
if 

me,theXableaus Ci) *nryRect.IsOverlapping{me.dragObj,matingRect) then 
If me,theTableans(i)* canlDrop{me,dragObj) then 
me.targetPile “ me.theTableans[1) 
exit 
end if 
end if 
next 

n “ uBound(nie.theFouiidations) 
for i = 0 to n 
if 

me.theFoundations{iJ.myRect.iaOverlapping(me.d ragObj.matlngRert) 
then 

if me.theFoundations{i).canlDrop(me.dragObj ] then 
me,targetPile = me.tbeFoundationa{i) 
exit 
end If 
end if 
next 
end if 


//or a tableau? 

m = uBound(me,tbeTafaleans) 
for j ” 0 to m 

if loe.theTableans(J),topGardDragging then 
me.dragObJ.matlngRect.xUL = x - me.dragObj.mouseOffsetX 
me.dragObj*matingRect.ytIL ” y - me*dragObJ^nxjiiseOfffiety 
me.dragObj.matingRect^xLR = ffle.dragObj,matingRject*xDL + wl 
me.dragObj.aatingRect*yLR = me,dragObj .matingRect.yUL + hi 
n ^ uBomdCme.theTableaus) 
for i ” 0 to n 
If 

me.theTableans(i).myRect.iaOverlapping(me.dragObj.matingRect) then 
if me.theTable aus(1).canlDrop{me.d ragOb j) then 
me.targetPile = me.theTableaus{i) 
exit 
end if 
end if 
next 

n = uBound(me.theFoundations) 
for i " 0 to n 
if 

me»theFoundations(i).myRect,IsOverlapping(me.dragObj.matingRect) 

then 

if me.theFoundations(i),canlDtop(me.dragObj) then 
me.targetPile ” me.theFoundationsCi) 
exit 
end if 
end if 
next 
end if 
next 

me.repaint 

Kn.d Sub 

Windowl.Canvas1.dealCards: 

Sub dealCardaC) 

dim i.jnn as integer 
dim num as integer 

for i ^ 0 to 6 
for j = i to 6 
nnm “ num + 1 
if j = 1 then 

me,theTableaus(j),addCard(me.theDeck.getTopCard.true) 
else 

me.theTableaus{j).addCard(me.theDeck.getTopCard,false) 
end if 
next 
next 

//initialize thf score 

me.theScore me.theScore - 52 
Z/ssvE a state on the 
pushNewStateO 
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End Sub 


//save a state on the stadi 
pushNewStateO 
End Sub 

Wind owl * Canvas 1. HousetJp: 

Sub MouseUp{X As Integer, Y As Integer) 
dim success as boolean 
dim i,n as integer 
dim temp as integer 

if not gameOver then 
temp ^ me^theScDte 
me,dragging ^ false 
me.theDeck^topCardDragging = false 
if iiie,deckRectl-lsWithin{x,y) then 
me^theDeck^flip 
me,graphics.drawPicture 
dimCard,me-deckRectl.xUl^me.deckRectl.yUL 
else 

n " uBound(me,theTabIeaus) 
for 1 = 0 to n 

ine.theTableaus(l),tQpCardOragging = false 
next 

if me,targetPile <> nil then 

success ^ me.targetPile-dropCardsfme.dragOhj.temp) 
me,dragOhj,source.removeCards{me.d ragObj) 
me.dragObj = nil 
elseif me^dragObj <> NIL then 

//herc's wh^ wc implement piayng a ttrp card to a foiindaiion witli a dkit 
//in this case, me.targetf^ will be nil, hut methagObj will NOT 
for i “ 0 to 3 

if me.theFoimdationsCi) ,canTDrop{nie,dragObj) then 
success = 

me.theFoundatlons(i),drapCards(me.dragObj,temp) 

me,dragObj,source,removeCards(me.dragObj) 
me.dragObj ^ nil 
me.repaint 
exit //the fonnott loop 
end If 
next 
end if 
end if 

me.targetPile = nil 
mettheScore = temp 
me,repaint 
end if 
End Sub 

Windovl,Canvas!,MouseDown r 

Function MouseDown(X As Integer* Y As Integer) As Boolean 
dim i.n as integer 

if not gameOver then 

if me.deckRectS.isWithin(x*y) then 
me,dragObj = 

me,theDeck. getDragCard [x.y.me.deckRect2 ,yUL.me,deckRect2 *xtJL) 
me,dragging - true 
else 

far 1 “ 0 to 6 

if me*theTableaus(i),myRect,isWithin{x,y) then 
n = uBound(ffie,tbeTableaus(l),theCarde) 
if n > -1 then 

if iiie,theTableaus{i) .theCards(n) .faceUP then 
me,dragObj = me,theTableaus(1),getDragCards(x.y) 
me*dragging = true 
else 

me.theTableausCi),theCards(uBound{me,theTableaus(l)*theCardsJ),f 
aceCP = true 

pushNewState C) 
cardDownSound.play 
end if 
end If 
end if 
next 
end if 
return true 
end if 

End Function 

Windowl,Canvas1,Open; 

Sub OpenO 

dim i as integer 
//initilaizc the ptjsition of our deck nectangljes 
me.deckRectl ^ new aRectangle(20,220,wl.hi) 
me,deckRect2 ” new aRectangle{20.320,wl,hl+44) 


Window1.Canvasl,Paint: 

Sub Paint(g as Graphics) 
dim l,c*w as integer 
dim s as string 

if windowOpen then //dont diaw into! he window unless tt ready 
g.foreColor = backGroundColor 
g.fillRect 0 * 0.me.width * me.height 
//dniw the deck 

me,theDeck,drawSelf(g.me.deckRecti,me.deckRect2) 

Z/diaw each fb the mhleaux 
for i = 0 to 6 

me.theTableaus(i)* drawSelf(g) 
next 

//and each of the foundahons 
for i = 0 to 3 

me,theFoundations(i)* drawSelf{g) 
next 

//if we arc dragging then draw the drag ub^’s pin 
if me,dragging then 

If me.dragObj <> NIL then 

g,drawPicture me.dragObj.thePic.me.dragX ■ 
me.dragObj*mouseOffsetX.me*dragY ■ me*dragObj.mouseOffeetY 
end if 
end if 

if shovSeore then 

me.dravSeoreCg,480* 20) 
end if 

if gameWon then 
for 1 = 0 to 51 

g.drawPicture packOfCardsCi).cardPic,rnd*{self,width - 
wl)*rnd*(self^height - hi) 
next 

c = roiind(md) *255 
g,foreColor ^ rgb{c,0,0) 
s “ “You Win i1” 
g.textSize ”110 
w ^ g*stringWidthCs) 

g.drawstring s.(me.width - w)/2,me,height/2 + IS 
end If 
end if 
End Sub 


// stt Cinlinc Ctxk 

Qad 

// sc* online code 

app 

//sc* online code 

QudConstants 

// see online code 

Glohals 

deck,deck: 

Sub deckCfl as boolean) 

//constructor 
dim i as Integer 

deck 

flipThree ^ f3 
for 1 = D to 51 

me,theCards * append packOfCards(1) 
next 

currentCard ” -1 
clearStatesC) 

End Sub 


deck,drawSelf: 

Sub drawSelf(g as graphics,! as aRectangle* 

R as aRectangle) 


dim xl.yl,x2.y2 as Integer 

dim dY as integer 

dim l.n.numCurds.nutiUP as integer 


xl = L*xUL 
yl = L-yOL 
x2 - R.xUL 
y2 - R*yUL 
if not gameOver then 

g.drawPicture cardBack, xl.yl 
g.drawPicture dimCard, x2.y2 
if curtentCard > -1 then 
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if fllpTbree then 
n = 2 
nlse 
n = 0 
end if 

n ^ miTv(n»curreiitCard ) 
niunCards = uBoundCtheCardfi) 
for 1 = 0 to numCards 

if theCardsU)‘fanelTP then 
numUP = nmaUP + 1 
end if 
next 

If numUP = 0 then 

theGards[currentCard).faceUP « true 
and If 

for 1 “ -n to 0 

if theCardE(currentCard + i).faceUP then 
g.drawPicture theCardn [currenrCard + 1) .catdPlc .3t2 .y2 + dY 
dy = dY + 19 
end if 
next 

if dY > 0 then 
dY = dY - 19 
end if 

if topCardDragging then 

g. drawPicture ditnCard, x2 {numUP-1) * 19 

end if 
else 

g.dravPlctnrG doneWithDeckCard» xl*yl 
end if 

else //game cjn-vr 

g.drawPicture gaiaeOverCard* xl*yl 
end if 
End Sub 

deck.shuffle: 

Sub shuffle 0 

dim i.j an integer 
dim tempCard as card 
dim tl*t2 as double 

tl “ microseconds 
shuffleSound* playLooping 
do until t2 > tl 1750000 
J = rnd*52 

tempCard ^ theCardsCj) 
theCards.remove j 
j = rnd*51 

theCards.Insert j»tempCard 
t2 = Jiticrosecofids 
loop 

for i " 0 to 51 

theCards(l).faceUP - false 
next 

curreiitCard “ 1 

shuffleSound.stop 
End Sub 

deck.flip: 

Sub flipO 

dim i.n.numGarda as integer 
dim nevCurrentCard as integer 

If not gsmeOver then 

nuinCards = uBound (theCards) 
carddownSound.play 
if not done then 
if flipThree then 
n = 3 
else 
n = 1 
end if 

//titm them ull ficc down 
for i =0 to current Card 
theCards(i)-faceUp ^ false 
next 

newGurrentCard = min(currentCard 1 n^numCards) 
if newCuTrentCard = numCards then 
done = true 

ttmesThroughDeck ^ timesThroughDeck + 1 
if strict then 
If flips then 

gameOver = (timesThroughDeck ^ 3) 
else 

gameOver = (timesThroughDeck = 1) 
end If 


end if 
end if 

if newCurrentCard <“ numCards then 

for i = currentCatd + 1 to newCur rent Card 
theCards(i).faceUP - true 
next 

currentCsrd = newCurrentCard 
end if 

else //the deck IS done 
n = uBound(theCards) 
for i = 0 to n 

theCards (i] *faceUp false 
next 

currentCard = -1 
done = false 
end If 

gameDnderWay *= true 
puahNewStateO 
end if 

End Sub 

deck.getTopCard; 

Function getTopCardO As card 
dim tempCard as card 

tempCard =■ theCards (0) 
theCards.remove 0 
return tempCard 

End Function 

deck.getDragCard' 

Function getDragCard(x as Integer.y as integer.t as integer.! 

as integer) As dragObject 
dim d as dragObject 
dim p as picture 
dim topCardTop as Integer 
dim l.nmtiCarda.numUP as integer 

if currentCard > -1 then 
nuinCards = uBound (theCards) 
for 1 = 0 to numCards 

if theCarda(i).faceUP then 
numUP = numOP + 1 
end if 
next 

topCardTop ^ t + (nuraUP-U'lS 

if y < topCardTop + hi then 
d = new dragObject 
d. source me 

p ■ [iewpicturG(dragCard.vldth.dragCard.height,32} 
if p ^ nil then 

msgBox “NIL PIC IN deck.getdragcards" 
end if 

d.theCards.append me.theCa rds(currentCard) 
d.matingCard = me.theCards(currentCard) 
p.graphics,dravPicture dragCard,0,0 
p.graphics.drawPicture d.theCards(0).cardPic*0.0 
p.mask.graphics.drawPicture dragShadow2.0.0 
d.thePic “ p 
d .mouseOffsetX x - 1 
d.mouseOffsetY = y - topCardTop 
topCardDragging “ true 
flySound.play 
return d 
end if 
end if 

End Function 

deck.removeCards; 

Sub removeCards(d As dragObject) 
me.theCards.remove currentCard 
currentCard = currentCatd ■ 1 
pushNewStateO 

End Suh 

deck.Statestring: 

Function stateStrlngO As string 

//save a string itpresenMon of the cunrait state of the deck 
dim s as string 
dim i.n as integer 

If flipThree then 
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s = 


el^e 
s = 
end if 


“31" 

“ll" 


s = s + strCcurrentCard) + ”1” 
If gameUnderway then 

s = s + “gameUnderWa7'‘+**| “ 
else 

s = s "I" 
end if 

If gaineOvei: then 

s = s + "gaineOver"+" I ” 
else 


s ” s + “ ■' 
end if 

if done then 

s - s + **done“+”[" 
else 

e = s + "I* 
end if 


n = iiBound(theCards) 
for i = 0 to n 

s " s + theCardsd) .Statestring + 
next 


return s 
End Fimctlon 

dech,restoreState: 

Snb rentoreState(stalestr as string) 

//restorc the slate of the deck tepiesented in the string saved hy the stateString method 

dim SpCardStr as string 
dim i.ii.y as integer 

B “ nthFieldCstateStr, 
me.fllpThree = (a “ "3’') 
s ^ nthField(stateStr,"|",2) 
me.currentCard = val(E) 

gameUnderWay = (nthFteld(stateStr ”*3) = “gameUnderWay'*] 
gameOver = (nthField(stateStr/‘I " .4) =* "gameOver") 
done - (nthFleld(stateStr .""I "*5) = **done'‘) 
s ^ nthFieid(stateStr," I'■ ,6) 

n = cDnntFieids(s, ".■*) 


redim me.theCardst-1) 
for i = 1 to n 
if s <> then 

cardStr = nthField(s."'."*i) 
if cardStr <> then 
V = vai(cardStr) 
if V > 51 then 
V = V ' 32 

packOfCards(v).faceUp ” true 
else 

packOfCardsCv]»faceUp = false 
end If 

me.theCards.append packOfGarda((v)} 
end if 
end if 
next 
End Sub 

deck.CardCount: 

Function CardCountO ^ Integer 
return uBound(theCards) + 1 
End Function 


// see onBne code 


SnioothCanvjs 


CaidCanvJS 

CardCanvas.dealCauda: 

Sub dealCardsO 
dealCarda () 

End Sub 

CardCanvaa.nevCame: 

Sub newGame(flips aa boolean) 
dim i as integer 


cedim theFoundations(‘1) 
rediiD theTableaunC l) 

me.tbeDeck “ new deck(flip3) 
me.tbeDeck.abuffle 
for i ^ 0 to 6 

me.theTableaus*append new tableau(new 
aRectangle{110+65»iJ 20,wl,hi)) 
next 

for i = D to 3 

me * t heFoundationa.append new foundation[new 
aRectangle C110+9 7*1*10.wl,hl)) 
next 

dealCarda 

timesThroughDeck = 0 
me.repaint 

End Sub 

CardCanvas * d r awSco r e i 

Sub drawScore(g aa graphica.x as Integer*y as integer) 
dim i*n as Integer 
dim a as string 
dim neg as boolean 

g.forecolor = rgb(0,0,0) 
g.textSize “ 12 

neg “ (tbeScore < 0) 
a = “Score: “ 
if neg then 

g.forecolor = rgb (255,0.0) 
a “ a + “ - " 
end If 

s = s + + str (abs(thfiScore)) 

g.drawString s.x.y 
End Sub 


Felt Tip 

Sound Studio 

Record and Edit Audio 

with a sound editor designed for the Mac. 

Sound Studio will allow you to make quick edits with an 
interface as easy as a text editor. Add polish to recordings 
with fades, normalization, and edits. Create your own mixes. 
Transform them with effects. 

Sound Studio features 
> up to 16 bits, 2 channels, and 66 kHz 
■ up to 2 GB of audio 

* AIFFt Sound Dtaipicr 2^. WAVE, 

System 7 Stuiad. and QuickTime import 

* edit with sample accuracy 

* fade, amplify, normalize, and invert 

* delay, echo, reverae, and swap channels 

* smooth and emphasize 

* rpsainplo and pitch shift 

* snap to zero crossings, snap to grid 

$35 

Sound Studio 

download free 14-day trial 
or order online at 

www.felttip.com 

OmckTiHtg l> j used undcf htjme _ pnCBW Lft dolUn 


Felt Tip Software, a07 Keeiy Place, Phiiadelphia PA 19123-2326, USA 
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Awaken the Guru Within You 


The pressure is on. You've got deadlines to hit, high expectations 
to meet, and complex technology issues to resolve. And just 
when the challenges you face on the Web are intensifying, 
along comes mobile technology. 


Successful Web teams depend on WEB2001 to help them 
anticipate, evaluate, and implement the latest Web strategy, 
user experience, and technoiogy. This year, the newly launched 
Internet+IVlobile conference will also prepare you to leverage 
mobile technology to extend your Internet enterprise. 


Now you and your team must create Internet and mobile 
solutions that raise your organization to a whole new level of 
efficiency and productivity. Clearly, the path to technological 
nirvana has never been easy. WEB2001 and Internet+Mobile 
can show you the way. 


Gain essential knowledge from the masters of the Web and the 
pioneers in mobile. Be inspired by fellow gurus from the far 
reaches of the earth and right next door. And meet the technology 
providers that will transform your business strategies into reality. 














Five days. Two conferences. One exposition. 
One all-access pass. Now that's good karma 


September 4th - 8th, 2001 
Moscone Center, San Francisco 


Join Us WWW.WEB2001SHOW.COM 





















Card Canva s * updateWinningGameSc ore: 

Sub updateWinnlngGameScoreO 
dim i*n as integer 


theScore “ theScore + me.theDeck.cardCount * 5 
for 1 ^ 0 to 6 

theScore - theScore + me.theTableaus(i).cardCount*3 
next 

End Sub 

CardCanvas.stateString: 

Function stateStringt) As string 
return str(theScore) 

End Function 


CardCanvas.restoreState: 

Suh restoreState(stateStr as string) 
theScore = val(stateStr) 

End Sub 


// se*? online axle 

soundGkibals 

// set; online code 

aRecmngle 


mbkau 


tableau,tableau: 

Sub tableau(r as aHectanglej 
me,myRect = r 
End Sub 

tableau*addCard: 

Sub addCard(c as card,fUP as boolean) 


tbeCards,append c 
c*faceUp “ fUP 

End Sub 

tableau.drawSelf: 

Sub drawSelfCg as graphics) 
dim x^y,dY,nuinUP as integer 
dim i,n as integer 

n = uBound (theCards) 
numUp “ 0 
X = myRect*xUL 
y = myRect*yUL 
g.drawPicture diniCard,x,y 
for i 0 to n 

If theCard5(i)-faceUp then 

g.drawPlcture theCards(i)*cardPic,x.y 
y = y + 19 
nuntUP = nuioUP + 1 
else 

g.drawPlcture cardBack,x,y 
y = y + 3 
end if 
next 

If numUP - 0 then 
numUP = 1 
end If 

if n - -1 then 
n = 0 
end if 

myRect.yLR = myRect^yUL + hi 
dY = (numtJP - 1)‘16 + (n)*3 
myRect.yhR = myRecttyLR + dY 
if me^couldAccept then 

g.drawPicture hillteCard.myRect.xUL+myRect,yLR ■ hi 
CQuldAccept - false 
end if 

if topCardDragging then 

g,d rawPicture myDimCard < myRect.xUL *myRect,yLR - 
myDimCard.height 

end if _ 

End Sub 

t ab1e a u,c anIDr op: 

Function canl£)rop(d as dragObject) As boolean 
dim n as integer 


couldAccept = false 
n ^ uBound(me,theCards) 
if n > -1 then 

couldAccept (d,matingCard*isRed O me *theCards(n)*isRed) 
and (d.roatingCard-cardVal = me.theCardsCn),cardVal - t) 
else 

couldAccept ^ [d*niatingCard*cariiVal = 12) 
end if 

return couldAccept 
End Function 

tableau,dropCards: 

Function dropCards[d As dragObject.byRef theScore as integer) 

As Boolean 

dim i*n ae integer 

n = uBound(d*theCards) 
cardDownSound.play 
for i = 0 to n 

d.theCardsCi)*faceU? “ true 
me * theCa rd s,append d.theCarda Ci) 
next 

gameCnderWay = true 
End Function 

tableau.removeCards: 

Suh removeCards(d As dragObject) 
dim iij^mtU as integer 

u = uBound(d*theCards) 
for i 0 to n 

m = uBound(me.theCardsj 
me.theCards,remove m 
next 

pushNevStateO 
End Sub 

tableau * getDragCardE: 

Function getDragCards{x as integer.y as integer) As dragObject 
dim d as dragObject 
dim p.pMask.tempPic as picture 
dim hottomCard as Integer 
dim i*numCards.numUPpCurTop as integer 
dim picHt as integer 

if not gameOver then 

hottomCard = whlchCard{y} 
d = new dragObject 
if strict then 

if hottoittCard uBound (theCards) then /Ainlew it’s tbc top card... 
for 1 “ D to (bottomCard-1) 
if theCards(i)*faceUP then 
return d 

//well nftiim a nul sino: ihr phycr cannot pla>^ a partial lun... 

end If 
next 
end if 
end if 

if theCards(bottomCard}.faceUP then 
//don’t even consider face (k>wn cards 
d.source = me 

numCards = uEound(theCards) 

picHt = dragCard.height + (numCarda ' bottomCard)M9 
p = newpicture(dragCard.width.plcHt.32) 
if p = nil then 

msgBox "NIL PIC IN tableau*getdrageards" 
end If 

myDimCard ” newpicture(wl.picEt-14*32} 
if p = nil then 

msgBox "NIL PIC IN tableau*getdrageards” 
end if 

pMask = newpicture(dragCard.width,picHt*8} 
if p = nil then 

msgBox "NIL PIC IN tableau,getdrageards" 
end if 

p* graphics *foreColor = j:^.( 0^0*D) 
p,graphics.fillreel 0.0 < p *width,p,height 

for i - bottomCard to numCards 
d.theCards.append me,theCards{i) 

p * graphics * drawPicture me * theCards(i)* cardPic,0,curTop 
p * graphic s * d rawPictur e tempPic.0.curTo p 
if i == bottomCard then 
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pKask.graphics.drawPicture dragShadow2,0,curTop 
else 

pHask. graphics, dravPicture d i:agShadow3,0 * curTop 
end if 

if i == hottomCard then 

myDimCard. snask.graphics,drawPicture 
diinCardMask. 0, curTop 
else 

myDimCard * mask.graphics.drawPicture 
d i TuCardMa sk2,0, curTop 
end if 

curTop = curTop +19 
next 

d.matingCard = me. theCards(bottotnCard) 
d^thePic ^ p 

d.mQuseOffsetX = x - nse.iDyRect.xtJL 

d,mouseOffsetY = y - topOfCardY(bottoDiCard] - myRect.yOL 
topeardDragging = true 
end if 

p ^mask.graphics.drawPicture pMask.0.0 
flySound.play 
return d 
end if 

End Function 
tableau.whlchCard: 

Function whlchCard{canvasY as integer) As integer 
dim i.n,testy as integer 

teatY ^ 0 

n = uBoundlme,theCards) 
for i - 0 to n 

if testy > canvasY-myRect .yUL then 
return i - L 
end if 

If the Cards Cl) . facelJP then 
testY = tsstY + 19 
else 

teatY ^ teatY + 3 
end if 
next 


return n 

//If wc'w gotten here,it must be the top caid... 

End Function 

tableau.topOfCardY: 

Function topOfCardYCtheIndex as integer) As integer 
//this htnetion wiB return the top of the spetihed eapd in local cixwdinateN 

dim i*n.curTop as integer 
n. ^ uBoundCtheCards) 

for i = 0 to n 

if i = theindex then- 
exit 
end If 

if theCardsCi)-faceUP then 
curTop = curTop +19 
else 

curTop = curTop + 3 
end if 
next 

return curTop 
End Function 

tableau.stareString: 

Function stateStringC) As string 

//savt a string representation of the current state of this tableau 
dim & as string 
dim i*n as integer 

s “ myRect.stateString + " |" 
n = uBoundCtheCards) 
for i = 0 to n 

s “ s + theCards(i).stateString + “." 
next 

return s 
End Function 

tableau.restoreState: 

Sub restoreStateCatateStr as string) 

//restore the state of this tableau represented in the string saved by the stateString 
mcthtxi 

dim s.cardStr as string 
dim i.n.v aa integer 
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s = nthFiel<l(stateStr.”|",!) 
me.myRect.restoreState(s) 
s ^ nthFieldCstateStr,"] 
n “ countFieldsCs,",”) 
redim me.tliGCardsE’l) 
for i = 1 to n 
if s <> *"'* then 

cardStr “ tithEieldEs.*,**,!) 
if eardStr <> then 
V “ val(cardStr) 
if V > 51 then 

V - V - 52 

packOfCardsEv)»faceUp “ true 
else 

packOfCardflCv) * faceup = false 
end if 

me.theCards,append packOfCarda((v)) 
end if 
end if 
next 

End Euh 

tableau, allFacetlp: 

Function allFaceUpO As boolean 
dins i*n as integer 

if uBound(me.theCards) <H} then 
return true 
end if 

n ^ uBoundEtheCards) 
for i = 0 to n 

if not tbeCardsEl).faceUP then 
return false 
end if 
next 

return true 
End Function 

tableau,cardCount: 

Function cardCountE) As integer 
return uBound(theCards) + 1 
End Function 


pounduicin 

Foundation.foundation: 

Sub foundation(r as aRectangle) 
me,iayRect = r 
End Sub 

Foundation,addCard: 

Sub addCardEc as card) 
theCarda.append c 
End Sub 

Foundation,drawSelf: 

Sub drawSeifEg as graphics) 
dim x.y.dY,nijmUP as integer 
dim l,n as integer 

n ^ uBouud(theCards) 

X “ myRect-xUt 
y ^ myRect.yUL 


g.drawPicture dlmCard.x.y 
if n > -I then 

g.drawPIcture theCards En),cardPic.x.y 
end if 

if me.cOUldAccept then 

g .drawPIcture hiliteCard. sryRect. xUL. my Rent, yUL 
couldAccept = false 
end if 
End Sub 

Foundation.canIDrop r 

Function canIDrop(d As dragObject) As Boolean 
dim n as integer 

couldAccept = false 
n = uBound(d.theCards) 

if n <> 0 then //^ can only one card to a foundation 


return couldAccept 
end if 

n = ufloundErne*theCards) 
if n > -1 then 

couldAccept = (d*matingCard*cardSult = 
me,theCards(n).cardSuit) and Ed.matingCard.cardVal ” 
me*theCardsCn).cardVal + L) 
else 

couldAccept = (d.matlngCard^cardVal = 0} 
end if 

return couldAccept 
End Function 

Foundation,dropCards: 

Function dropCards(d As dragObject*byRef theScore as integer) 
As boolean 

cardDownSound ^play 
d.theCardsEO).faceUP ^ true 
me.theCards.append d.theCards(0) 
theScore “ theScore f 5 
gamellnderWay ^ true 
return true 
End Function 

Foundation.stateStrlng: 

Function stateStriugd As string 
//save a string reptesentation of die oiment state of this foundation 
dim s as string 
dim i,n as integer 

U “ uBound(theCards) 
for i ^ 0 to n 

s “ s + theCards(i)-StateStrlng + 
next 

return s 
End Function 

Foundation-restoreState: 

Sub restoreStateCstateStr as string) 

//restoit: the state of this foundation represented in the string saved by the stateStiiug 
method 

dim l.n^v as integer 
dim s.cardStr as string 

n ^ countFields(EtateStr 

redia tae.theCardsE'l) 
for 1 = 1 to U 

cardStr = nthField (stateStr i) 
if cardStr <> then 
V val (cardStr) 
if V > 51 then 

V “ V - 52 

packOfCardsEv) .faceup true 
else 

packOfCardsEv).faceUp " false 
end if 

me.theCards.append packOfCards((v)) 
end if 
next 
Eud Sub 


diagDbjea 

dragOb j GC t.d ragObj ec t: 

Sub dragObjectf) 

//the ‘^madngRcci'’ is the rectuiglt tiut we will test for overiap with each 
// tableau and foundation 

me.matingRect = new aRectangleE0*0,wl»hl) 

End Eub 

UroppabiePllG.canIDrop: 

Function canIDropEd as dragObject) As boolean 
Eud Function 


DroppablePile 

Dro p p ablePil g. d topCard a t 

Function dropCardsEd as dragObject,byRef theScore an integer) 

As boolean 

End Function 

dropSource.removeCards; 

Sub removeCards(d as dragObject) 

End Sub 
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stateMadiine 

stateMachlne,tbeStateString: 

Function theStateStringO As string 
dim i,n as integer 
dim s as string 

s = globalsStateStrlng + 
s = s + wlndovl < canvasl. stateString 
E " a t windowl.canvasl .rlieDeck.stateStriiig 
for i = 0 to 6 

s " s + wlndowl. canvas I ,theTableaus(i) *stateStrliig + 
next 

for 1 = 0 to 2 

s = a + windowl,canvas 1.theFoundations(i) .stateStrlng + 
nest 

s = s + windowl.canvasl.theFoundations(3).Statestring 
return 3 
End Function 

stateHachine.restoreTheState: 

Sub restoreTheStateCstateStr as string) 
dim i.n as integer 
dim s as string 

restoreGlobals(nthField(stateStr . 1)) 
wltidowl. canvas!. reEtorEState(nthField (etateStr. * 2)) 
windowl,canvasl.theDeck.restoreState(ntliFlcld(stateStr *.3)) 
for i ~ 0 to 6 

wlndovl.canvas1,theTableaus(i)* restoreState{nthField(stateStr."& 
M+4)) 
next 

for i ^ 0 to 3 

window!.canvas1 * theFoundations(i),restoreState(nthField C stateStr 
next 

windowl.canvasl.repaint 
End Sub 

StateHachine.initStateHachine: 

Sub initStateMachineO 
currentState ‘1 
End Sub 

StateHachine * undoAvallable: 

Function undoAvailableO As boolean 
return currentState ^ 0 
End Function 

StateHachine.redoAvailablei 
Function redoAvailableO As boolean 

return uBound{EtateArray) } currentState 
End Function 

StateHachine,pushNewState: 

Sub pusKNewState0 
dim l*n as integer 
diin s as string 

//first we need to pop olf iuiything above tiur cuntnt state.. 

n = uBound(stateArray) 
for i - currentState^l to n 

stateArray* remove (currentState+l) 
next 

s = theStateString 
stateArray,append s 
currentState = uBoundCstateArray) 
if hasGameBeenWon then 
doGameWi uRoutine 
end if 

//now well rabe our flag to mark us as dirty 
gDirty = true 
End Sub 

stateMachine.undo: 

Sub undoO 

currentState = currentState ■ 1 
reatoreTheStatefEtateArray(currentState)) 
undoSound.play 
End Sub 

StateMachine.redo: 


Sub redoC) 

currentState ^ currentState + 1 
undoSound,play 

restoreTbeStata(stateArray(currentState)) 

End Sub 

StateMachine.clearStates; 

Sub clearStatesO 
redim stateArray(-1) 
currentState = -1 
End Sub 

StateMachine.StartOver: 

Sub starcOverC) 

dim i.n as integer 

n = uBoundCstateArray) 
for i = n doMito 0 
currentState = 1 
restoreTbeState(stateArray(1)) 
undoSound.play 
next 
End Sub 

StateMachine,saveGameFllei 
Function saveGameFileO As boolean 
dim f as folderltem 
dim tos as textOutputStream 
dim i.n as Integer 

f = getSaveFolderltemt^TEXT'’. ^'myGanie"’) 

If f 0 NIL then 

tos = f.createTextFile 
if tos 0 NIL then 

n = uBound(stateArray) 
for i = Q to n 

tos.writeLlne stateArray(l) 
next 

tos.close 
gDirty == false 
return true 
end if 
end if 
return false 
End Function 

s t ateMac hine.op enGameFile: 

Function openGameFileO As boolean 
dim f as folderltem 
dim tls as teixtlnputStream 
dim s as string 

f = getOpenFoldGrItem{"TEXT") 
if f <> NIL then 

tis = f,openAsTextFlle 
if tis <) NIL then 
clearStatesO 
while not tis.eof 
s = tis.readLine 
StateArray.append s 
currentState ” uBound(stateArray) 
wend 

restorsTheState(stateArray(currentState)) 
gDirty — false 
return true 
end if 
end if 

return false 
End Function 


Abr>umNc]g 

// set online code 


PtdsWin 

//set udine code 


AkftWin 

// see online code - 
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Not Your Average 

Wireless Access Point 





aCf/» 


Famllon 


ivww.faradoii.com 


Share your high"Spe6d Internet connection 

with both wired and wireless computers while 

protecting your data from unauthorized access. 


The NetLINE Wireless Broadband Gateway allows you to 
share a high-speed Internet connection, such as Cable or 
DSL, with multiple computers using just a single IP 
address from your ISP, Support for both 802.1 lb wireless 
and standard Ethernet connections are built-in to this router 
and access point all in one. 


The built-in firewall wiU protect your important files by 
preventing unauthorized access via the Internet and the 
web-based configuration makes set-up a breeze. 


100% compatible with SkyLINE^ Airport^ 
and all other 802.Ilb wireless cards. 

For more information contact Dr. Farallon 
at 1-800-613-4954 or visit us on the web at 

www.faraUon.com. 
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SSH 

When the Internet was first growing up^ it was developing 
in a rather safe environment. In fact, to the inventors it was 
probably a miracle that it worked at all Now^ however, those 
halcyon days are gone, and we live in less innocent times, 
where security is a genuine concern—it isn't practical these 
days to just assume that things will be safe by default. There 
are a number of steps that users need to take these days to 
secure their systems, and this month we are going to look at 
one of them, ssh. It's a small but important piece* 

What’s ssh? 

In brief, ssh (the Secure Shell) is a cryptographically 
secure replacement for telnet. The name is actually a bit of a 
misnomer—it isn’t really a shell Itself, but rather a mechanism 
for interacting with a remote shell over a secure 
communication channel It's an indispensahie tool for 
working with Mac OS X in a networked environment—like 
telnet, it allows you to quickly connect to remote machines, 
which is handy if not essential for a variety of administration 
and other tasks. In fact, the most significant security 
enhancement that ssh gives you may not be that it encrypts 
the contents of your remote session (which it does), but 
rather that it encrypts the login exchange itself, meaning that 
your password is never sent unencrypted over the network. 
Even in a supposedly secure environment, for instance 
behind a corporate firewall, it's a good idea to use ssh 
instead of telnet whenever possible (which basically means 
whenever the two machines which are communicating both 
have it installed), both because it adds an extra bit of 
security, and also because it will get you into the habit of 
using it and making sure it is installed and available on all 
machines you routinely connect to, so that when you are 
operating in a less secure environment (for instance, if you 
need to connect From off site) you will be in the habit of 
reaching for ssh and will l:ie opting for security by default. 

Mac OS X has ssh installed by default (as part of a 
regular update package), and you can use it to connect with 
remote machines without further setup. To enable 
connections to your machine you merely need to enable 
remote login In the Sharing pane of System Preferences (after 
the update which installs ssh on Mac OS X, this setting is 
connected to ssh rather than to telnet, which is then disabled 
by default). The ssh ‘'server'’ component (sshd) can be run 
out of metd, but it is more commonly run as a .standalone 
daemon. If you need to install ssh separately (either becau.se 
you wish to install a newer version or because your current 
install is damaged), there are instruction on Stepwise for 
building and installing OpenSSH under Mac OS X. (The 


article also includes instructions for compiling in support for 
using icpwrappers to further secure things by restricting 
remote login to a specific set of hosts and adding additional 
logging.) This version of ssh is free and open-source (part of 
the OpenBSD project, in fact), and leverages the OpenSSL 
library for many of its cryptographic algorithms. There are 
commercial versions available as weU (and older free version 
from commercial vendors), but for most users OpenSSH is a 
good choice. OpenSSH tries very hard to avoid the use of 
patented algoritlmis in its implementation, in order to avoid 
the attendant restrictions to free development and 
distribution, and consequently does not support some of the 
algorithms found in commercial versions. This can be seen as 
either a virtue or a shortcoming, but in practice it does not 
interfere with its use. 

Building OpenSSH 2.9 on Mac OS X 10.0.x 
<http://wvw.stepwise.eom/AEticlesyWorkbench/2001-05-02.03,html> 
Securing your Host—^tepwrappers 
<http://vvvvw.theofygroup.comyT1ieory/Systems/tcpvvrappers.html> 

The SHH Suite 

Overall, ssh has a great deal of flexibility in the details of 
its use. It supports a variety of authentication schemes, from 
RSA or Kerberos-based authentication to simple passwords or 
automatic login between trusted hosts; you can choose from 
several different algorithms (also called ciphers) for the 
encryption; and you can use ssh for pon-fbrwarding to wrap 
insecure protocols inside of a secure transfer stream. And in 
addition to enabiing remote login sessions, the ssh distribution 
contains several related tools which take advantage of ssh’s 
base Facilities for secure communication. For file transfer, there 
is sep (an analog of rep and ultimately cp, if you are familiar 
witli tltose), which is tised to copy files between systems over 
an ssh-based, encrypted channel Server environments today 
are often set up without ftp installed in order to enhance 
security, and in such situations sep is the tool of choice for 
moving files onto and off of these systems. In addition to 
encryption, sep also supports compression of files during transit 
in order to speed transfer, using the same algorithm as gzip. 
(Compression i.s also supported by ssh itself, but the benefits 
are more likely to be noticeable during large file transfers than 
during a standard interactive login session, although over skjw 
connections compression could make ssh ''faster” than telnet 
for interactive use.) The sep tool has the same semantics as cp, 
so that source and destination are specified when invoking the 
tool, rather then being chosen interactively as is commonly 
done with ftp tools. Tliis can be somewhat inconvenient, as you 
need to know the exact path to use on the remote system 
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before invoking the tool, which will often necessitate a 
separate ssh login to ‘hrowse aresund” the remote Filesystem to 
determine the correct path. On the plus side, sep can be used 
to transfer files between remote systems—neither the source 
nor the destination needs to be local. 

On he oher hand, if you need the convenience and 
flexibility of the interactivity of ftp, you might And sftp more to 
your liking. It’s a newer addition to the ssh family, and is likely to 
be les.s widely deployed at this time. It provides an ftp-like 
interactive session for file transfer, with similar commands to hose 
used by ftp. Technically, sftp is not itself a secure protocol, but 
rather it is a protocol designed to be used over a secure channel, 
provided by ssh. Ihere is a separate executable, sfip-sewer, wldch 
is used by OpenSSH to enable sftp on he server side, bui it is 
invoked by the sshd diemon rather dxin running separately, so it 
requires minimal configufation and setup to get it running. One 
caveat is hat sftp is reported to be significantly slower tlian the 
traditional sep, aldiough it's not dear wheher hLs is inherent to 
the protocol it uses, or if ifs just he result of a still-evolving 
implementation. Note also that sftp is not simply ftp secured via 
ssh port-forwarding, Ix^cause ftp's use of two separate TCP/IP 
connections for control commands and data transfer makes his 
difficult to do; instead, sftp uses a single stream to do its work, 

References 

Online, you can find most of the essential information 
you need at the OpenSSH web site, including download 
locations, online manual pages, and a short FAQ, as well as 
links to oUier sites with articles and even more information. 
There is also another ssh FAQ available online, more general 
but somewhat geared toward the commercial versions of ssh. 

OpenSSH 

<http://openssh,org/> 

OpenSSH Manual pages 
<http:y/openssh.org/manu3LhtmI> 

OpenSSH FAQ 

<http://openssh.org/faq.html> 

OpenSSH Articles 
<http://openssh.org/press.html> 

The Secure Shell Frequently Asked Questions 
<http://www.tigerlaircom/ssh/faq/ssh-faqhtml> 

There are also a couple of lxx>ks available devoted entirely to 
ssh. They can provide you witii all the details and options you liave 
for setting up and using ssh on your systems, as well as using it for 
advanced applications such as tep port forwarding. Possibly more 
importantly, diey'U guide you tlirough the minefield of terminology 
surrounding different version of ssh products and pixjtocols (which 
are very easy to confuse), and spell out differences and 
interoperability Issues surrounding the different implementatioas. 
Try either SSH, The Secure Shell: The Definitive Guide (ISBN: 0-596- 
tX)011-l) from O'Reilly and Associates, or UNIX Secure Shell (ISBN; 
0071349332 ) from Ostx>rne. There is also an excellent web site to 
accompany the O'Reilly book, with extensive reference information 


and linRs to protocol specifications and other reference material. 

SSH, The Secure Shell: The Definitive Guide 
<http://www.snailbook.com/> 

For further helpful info, check out the top 10 FAQ list 
from Richard Silverman, one of the authors of the O'Reilly 
book. The securiry-minded user (which should be everyone, 
right?) will also want to check out a recent arficTe on 
SecurityPortal.com about a potential security weakness with 
ssh, as well as the follow-up rebuttal article from Richard 
Silverman which corrects some factual errors and gives a less 
alarmist perspective. For further security info, take a look at 
the OpenSSH Security page. 

Top Ten Secure Shell FAQs 

<http://sysadmin.oreilly.eom/news/sshtips_0101.html> 

Bie End of SSL and SSH? 

<http://www.securityportaLcom/cover/coverstory20001218.html> 
dsn iff and SSH: Reports of My Demise are Greatly Exaggerated 
<http://sys3dmin.oreilly,com/news/silverman_1200.html> 

OpenSSH Security 
<http://openssh.org/security.html> 

Finally, for tliose interested in .some of the more advanced 
features of ssh, start with the SSH Protoed Architecture intemet- 
dmft from the FFTTF for an extensive high-level overview of tlie 
protocol. Then, check out an article from the O'Reilly Nem^ork on 
using an ssh ainnel to inciease the security of 802. llh wireless 
networking, .such as that lused by AirPort. 

SSH Protocol Architecture 

<http://openssh.org/txt/draft-ietf-secsh-architecture-07dxt> 
Using SSH Tunneling 

<http://www.oreiliynet.eom/pub/a/wireless/200 l/02/23/wep,ht 
ml> 

If you are not yet using Mac OS X (and why aren't you, 
huh?), [hen you can still connect via ssh to remote machines 
using one of the two clients for the Classic Mac OS. There is 
NiftyTelnet SSH (based on NiftyTelnet itself) supporting the 
SSHl protocol, including sep capabilities, and MacSSH, 
which is a modified version of BetterTelnei supporting SSH2. 
Both are available free of charge. If you are running Mac OS 
X but would prefer a graphical file-transfer tool, try 
RBrowser, a GUI-based ftp tool which also supports ssh- and 
sep-based file browsing and transfer. It is still in beta testing, 
and will require a licensing fee once it is finah 

NiftyTelnet SSH 

<http://wwwJysator.liu.se/Honasw/freeware/niftyssh/> 

MacSSH 

<http://www.macsecsh.com/> 

RBrowser 

<http://www.rbrowserxom/RBrowser_main.html> HI 
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60 days of free instailation support 
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tool or your media-player; everything is included with the "'drag & 
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Our expert team offers you 60 days of individual installation support 
via phone. Fax or email. 


SuSE Inc. 

580 Second Street 
Oakland, CA 94607 

info@suse.corii 
Phone: (888) UR-LINUX 
(510) 628-33S0 
Fax; (510)628-3381 



Place your order today! www.suse.com 
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